API 通用说明 · 算邻坊开发者控制台

01快速开始

Base URL https://www.suanlinfang.cn/v1 （本地开发环境使用 http://localhost:8081/v1）

认证方式 Bearer nk-your-api-key Authorization header，API Key 在控制台「API Key 管理」页面创建

开放状态语音识别 / 语音合成 / 文字识别 / 智能决策已开放对话能力暂未开放；接口契约以下文为准

算邻坊 API 风格对齐主流大模型厂商：Bearer 密钥认证 + JSON 请求体，各产品接口契约以下文为准。

文件上传（OSS 直传）

语音识别（STT）与文字识别（OCR）涉及文件输入的接口，统一采用三步流：文件不经过平台服务器中转，由您直传对象存储（带宽高、速度快），平台经内网读取处理。

          text · 三步流
        
          ① POST /v1/{stt|ocr}/upload-tickets     申请上传签名 → 返回 uploadUrl + fileKey
② PUT  {uploadUrl}                      直传 OSS（headers 用签名响应里给定的值）
③ POST /v1/{stt|ocr}[.../tasks]         以 fileKey 提交业务请求

直传注意事项：① PUT 的 Content-Type 必须与签名响应 headers 里的值完全一致，否则 OSS 返回 403；② 签名 10 分钟内有效；过期重新申请即可——新签名会返回新的 fileKey 与 uploadUrl，请以新值重新上传并提交；③ 一个 fileKey 对应一次上传凭证，提交业务请求前请确保 PUT 已成功完成；④ TTS 为纯文本输入（JSON body），无文件直传环节；⑤ 上传请求的完整要素与 cURL/Python 示例见语音识别 / 文字识别接口页的异步章节。

python

import requests

# 第一个请求：语音合成
response = requests.post(
    "https://www.suanlinfang.cn/v1/tts",
    headers={"Authorization": "Bearer nk-your-api-key"},  # 在控制台 API Key 管理页面创建
    json={
        "reqParams": {"text": "欢迎使用算邻坊语音合成。", "speaker": "default"},
        "audioParams": {"format": "mp3"},
    },
)
print(response.json()["url"])  # 现签下载链接，GET 即得音频

shell

curl https://www.suanlinfang.cn/v1/tts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nk-your-api-key" \
  -d '{
    "reqParams": {"text": "欢迎使用算邻坊语音合成。", "speaker": "default"},
    "audioParams": {"format": "mp3"}
  }'

能力总览：语音识别 STT（单笔 + 长音频异步）、语音合成 TTS（单笔 + 长文本异步）、文字识别 OCR（单图 + PDF 异步）、智能决策（单笔同步，System One 协议）；文件类输入（STT/OCR）走 OSS 直传三步流。

02异步任务通用说明

语音识别 / 语音合成 / 文字识别三产品的异步接口共用同一套任务模型：提交即返回 taskId，平台异步拆分与执行，客户端轮询查询接口获取进度与结果。

任务状态机

状态	说明
queued	已受理，等待拆分（长音频切段 / 长文本切块 / PDF 拆页）
running	逐单元执行中，可通过 `doneUnits / totalUnits` 观察进度
success	任务完成（全部单元成功），`resultUrl` 返回聚合结果下载链接
failed	任务失败（任一单元经换点重试后仍失败即中止），`errorMsg` 字段返回首败单元定位与原因，无结果产物
expired	终态保留 72 小时后过期，结果不再可取

轮询建议（指数退避）

python · polling

import time, requests

BASE = "https://www.suanlinfang.cn/v1"
HEADERS = {"Authorization": "Bearer nk-your-api-key"}

def wait_task(path):                      # path 如 /stt/tasks/{taskNo}
    interval = 2
    while True:
        task = requests.get(BASE + path, headers=HEADERS).json()
        if task["status"] in ("success", "failed", "expired"):
            return task
        time.sleep(interval)
        interval = min(interval * 2, 30)  # 2s → 4s → 8s … 上限 30s

异步计费与二值终态：异步任务按单元逐笔计费（每段音频 / 每块文本 / 每页图片各计一笔），任务终态只有成功 / 失败两种——全部单元成功才为 success（返回完整聚合结果）；任一单元失败（平台已内部换节点重试仍未恢复）任务即为 failed，不产出部分结果，失败时已成功单元照常计费。费用明细可在各产品在线工具页的「历史记录」查询。任务提交前请确保账户余额充足，余额不足时提交将被拒绝（402）。

taskNo 保管：taskId（taskNo）请妥善保存；遗忘时可在任务历史接口 GET /v1/{product}/tasks 分页找回（终态保留 72 小时内有效）。

03错误码参考

错误响应统一返回 HTTP 状态码 + JSON body，格式为 {"error":{"message", "type", "code", "param"}, "requestId"}：code 为字符串业务码（如 "40201"，无业务码时不下发该字段），param 指向出错的请求参数（如 file、input，不下发时为空），requestId 为请求级追踪号（报障时请提供）；503 响应附带 Retry-After 头（秒），客户端按该值退避重试。

状态码	错误类型	说明
400	invalid_request_error	参数缺失或格式错误：文本超长、音频格式不支持（当前支持 wav/mp3/flac/m4a/ogg/aac）、图片格式不在白名单、单笔文件超上限、multipart 缺 file part、公网 URL 非法或指向内网地址（安全策略拒绝）、公网拉取失败、签名申请的扩展名不合法等。message 中给出具体原因。各产品均不指定模型（平台自动使用当前唯一在线模型），请求中传入 model 字段会被忽略。
401	authentication_error	API Key 无效、已删除或未传 Authorization header。密钥前缀应为 `nk-`。
402	insufficient_balance	账户余额不足，无法完成本次推理计费。请前往「账户充值」页面充值后重试。
404	not_found	查询的任务号不存在 / 不属于当前账号；或异步的 `fileKey` 不存在 / 尚未直传完成（40404）；或直传文件实际大小与申请签名时报备的 `sizeBytes` 不符（40405）。
413	request_too_large	申请签名时报备的 `sizeBytes` 超过产品上限（STT 异步 500MB、OCR PDF 200MB；单笔文件上限在识别接口侧校验）。
500	internal_error	服务内部错误，可携带 log_id / taskId 联系平台排查。
503	service_unavailable	当前模型无可用供给节点（全部离线或繁忙）。可稍后重试。
504	gateway_timeout	推理超时，请求已取消。短音频请确认时长在限制内（超限走异步）。

错误响应示例

          json · error response example
        

          {
  "error": {
    "code": "40201",
    "type": "insufficient_balance",
    "message": "账户余额不足，请充值后重试"
  },
  "requestId": "3f8a1c2e-9b4d-4e6f-8a1b-2c3d4e5f6a7b"
}
        