语音识别 API · 算邻坊开发者控制台

01单笔转写

将语音文件转写为文字。按输入形态二选一接口：/v1/stt/url（公网地址引用）或 /v1/stt/file（multipart 直传，支持 wav/mp3/flac/m4a/ogg/aac，≤20MB、3 分钟以内），同步返回转写文本；中文场景优化，非标准格式由平台自动转码。

Endpoint · url POST/v1/stt/url application/x-www-form-urlencoded

Endpoint · file POST/v1/stt/file multipart/form-data

请求参数（按接口归属，两种输入形态对应两个接口）

参数	类型	必填	说明
url	string	url 接口必填	音频的公网可下载地址（url ≤2048 字符，音频 ≤ 20MB），服务端拉取后转写；内网/保留地址会被安全策略拒绝
file（multipart）	file	file 接口必填	音频文件二进制（`wav`/`mp3`/`flac`/`m4a`/`ogg`/`aac` ≤ 20MB，格式按文件内容识别），一次请求直传
language	string	否	语种代码，缺省自动检测（22 种中文方言自动识别，无需指定）；强制指定可提升短音频/混语场景准确率；计费按音频实际时长计算。
context	string	否	热词/背景上下文（≤500 字符）：人名、术语、品牌等专有名词按所列写法优先转写，可逗号分隔列词或写一句场景描述

模型无需指定：平台自动使用 product 为 stt 的当前唯一在线模型。两接口参数同构；音频时长须 ≤ 180 秒、文件 ≤ 20MB，超限请压缩或使用异步任务接口。

shell

# 接口 1 · 公网 URL（服务端从该地址拉取音频）
curl https://www.suanlinfang.cn/v1/stt/url \
  -H "Authorization: Bearer nk-your-api-key" \
  -d "url=https://your-cdn.com/recording.wav" \
  -d "language=zh" \
  -d "context=算邻坊,随心翻译,RTF=1.0,讲师：王建国"

# 接口 2 · multipart 文件直传（一次请求闭环）
curl https://www.suanlinfang.cn/v1/stt/file \
  -H "Authorization: Bearer nk-your-api-key" \
  -F file=@recording.wav \
  -F language=zh

python

import requests

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

# multipart 文件直传，一次请求闭环
with open("recording.wav", "rb") as audio_file:
    resp = requests.post(f"{BASE}/stt/file", headers=HEADERS,
        files={"file": audio_file}, data={"language": "zh"})
print(resp.json()["result"]["text"])

响应示例

json · response

{
  "inferenceId": "5f2b8c3a-9d41-4e7a-b6f2-1c8d3a9e0b47",
  "result": {
    "text": "欢迎来到算邻坊，这里是语音识别的转写结果。"
  },
  "audioInfo": { "durationMs": 7400 }
}

计费按音频实际时长计算，单价以元/小时展示、精确到秒折算，详见计费说明。

02异步转写（长音频）

超过 3 分钟的长音频走异步任务：先申请上传签名、PUT 直传 OSS，再提交任务并轮询结果（wav/mp3/flac/m4a/ogg/aac，≤500MB，平台自动转码按段切分计费）。任务状态机与轮询约定见通用说明 · 异步任务。

申请上传签名

Endpoint POST/v1/stt/upload-tickets

Content-Type application/json 异步任务专用入口（单笔走 /v1/stt/url 或 /v1/stt/file 直连）

请求参数

参数	类型	必填	说明
fileName	string	是	文件名（含扩展名），仅用于存储命名与展示；扩展名须为 `.wav`/`.mp3`/`.flac`/`.m4a`/`.ogg`/`.aac`（决定上传 Content-Type）
sizeBytes	integer	是	文件大小（字节），≤ 500MB，超出拒绝签发

响应示例

json · response

{
  "fileKey": "inference-media/upload/1024/8f14e45f-eea7-4f5b-9c1d-2b6a9d0c1e3f.wav",
  "uploadUrl": "https://slf-media-stt.oss-cn-beijing.aliyuncs.com/inference-media/upload/...?Expires=...&Signature=...",
  "method": "PUT",
  "headers": { "Content-Type": "audio/wav" },
  "expireAt": "2026-09-27T12:10:00Z",
  "maxSizeBytes": 524288000
}

shell

# sizeBytes = 文件实际字节数（≤ 500MB）
curl https://www.suanlinfang.cn/v1/stt/upload-tickets \
  -H "Authorization: Bearer nk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"meeting-2h.wav","sizeBytes":241172480}'

python

import os

size_bytes = os.path.getsize("meeting-2h.mp3")              # ≤ 500MB
ticket = requests.post(f"{BASE}/stt/upload-tickets", headers=HEADERS,
    json={"fileName": "meeting-2h.mp3", "sizeBytes": size_bytes}).json()
# ticket["uploadUrl"] / ticket["headers"] → 下一步 PUT 直传；ticket["fileKey"] → 提交任务用

上传文件到 OSS

Endpoint PUT{uploadUrl}

Host slf-media-stt.oss-cn-beijing.aliyuncs.com uploadUrl 域名为阿里云 OSS（非平台域名）；签名已含在 URL 参数中，无需 Authorization 头

请求要素

要素	值	说明
URL	签名响应 uploadUrl	签名 10 分钟内有效；过期重新申请签名（返回新的 fileKey 与 uploadUrl，以新值重传）
Headers	照抄签名响应 headers	`Content-Type` 按扩展名映射（wav→`audio/wav`、mp3→`audio/mpeg`、flac→`audio/flac`、m4a→`audio/mp4`、ogg→`audio/ogg`、aac→`audio/aac`），参与签名，值不一致时 OSS 返回 403（SignatureDoesNotMatch）
Body	音频原始二进制	文件字节流本身，不是 multipart/form-data
成功	HTTP 200	无响应体（响应头含 ETag）；上传完成后 `fileKey` 即上传凭证，供下一步提交任务引用

shell

# URL 换成上一步签名响应的 uploadUrl（域名即 OSS，非平台）
curl -X PUT "https://slf-media-stt.oss-cn-beijing.aliyuncs.com/inference-media/upload/1024/8f14e45f-....wav?Expires=1761552000&Signature=..." \
  -H "Content-Type: audio/wav" \
  --data-binary @meeting-2h.wav
# 成功：HTTP 200，无响应体

python

# ticket = 上一步「申请上传签名」的响应；headers 直接用 ticket["headers"]，勿自行改写
with open("meeting-2h.wav", "rb") as audio_file:
    upload = requests.put(ticket["uploadUrl"], data=audio_file,
                          headers=ticket["headers"])
upload.raise_for_status()          # HTTP 200 即成功，无响应体

浏览器网页内也可直传：存储桶已开放 CORS（PUT / GET），前端拿到签名后用 fetch / XMLHttpRequest 发起同样的 PUT 即可。

提交任务与轮询结果

Endpoint POST/v1/stt/tasks

Content-Type application/json 提交后异步处理，任务状态与结果通过查询接口获取（见异步任务通用说明）

请求参数

参数	类型	必填	说明
audio.url	string	是	上传凭证（≤ 500MB，`wav`/`mp3`/`flac`/`m4a`/`ogg`/`aac`，由「申请上传签名」接口签发），平台自动转码并按 180 秒切段逐段转写
language	string	否	语种代码（与单笔同义，取值与说明见单笔参数表），对任务全部音频段生效
context	string	否	热词/背景上下文（与单笔同义，≤500 字符）：专有名词按所列写法优先转写，对任务全部音频段生效

模型无需指定：平台自动使用 product 为 stt 的当前唯一在线模型。

查询接口

Endpoint GET/v1/stt/tasks/{taskNo}

提交响应 / 查询响应示例

json · 提交响应

{
  "taskId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

json · 查询响应（success 时）

{
  "status": "success",
  "totalUnits": 6,
  "doneUnits": 6,
  "resultUrl": "https://oss.../result.json?Expires=...&Signature=...",
  "expireAt": "2026-09-27T12:00:00Z"
}

json · resultUrl 下载内容（result.json）

{
  "text": "全部段落的转写文本拼接…"
}

shell

# ① 提交任务（audio.url = 签名响应 fileKey；平台自动按 180 秒切段）
curl https://www.suanlinfang.cn/v1/stt/tasks \
  -H "Authorization: Bearer nk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"audio":{"url":"inference-media/upload/1024/8f14e45f-....wav"},"language":"zh","context":"算邻坊,随心翻译,讲师：王建国"}'

# ② 轮询任务（GET 至终态 success / failed / expired）
curl https://www.suanlinfang.cn/v1/stt/tasks/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer nk-your-api-key"

python

import time

task = requests.post(f"{BASE}/stt/tasks", headers=HEADERS,
    json={"audio": {"url": ticket["fileKey"]}, "language": "zh"}).json()

while True:                              # 指数退避版见 通用说明 · 异步任务
    query = requests.get(f"{BASE}/stt/tasks/{task['taskId']}", headers=HEADERS).json()
    if query["status"] in ("success", "failed", "expired"):
        break
    time.sleep(5)

print(query["resultUrl"] if query["status"] == "success" else query)

03历史记录查询

查询本 API Key 所属账户的语音识别调用历史；鉴权同产品端点（Bearer API Key），响应为分页 JSON（无信封）。

单笔历史

Endpoint GET/v1/stt/records

分页查询语音识别单笔形态的历史。

Query 参数

参数	类型	必填	说明
page	integer	否	页码，默认 1
pageSize	integer	否	每页条数，默认 10

任务历史

Endpoint GET/v1/stt/tasks

分页查询语音识别异步任务形态的历史。

Query 参数

参数	类型	必填	说明
page	integer	否	页码，默认 1
pageSize	integer	否	每页条数，默认 10

响应字段（items[] 内，null 字段不下发）

字段	类型	说明
form	string	single / task（单笔 / 异步任务）
status	string	processing / success / failed
taskNo	string	任务形态的任务号（单笔为 null 不下发）
inputCount	integer	计费输入计数（STT=音频秒，费用=秒数×牌价）
consumerCost	number	本笔消费金额（元）
elapsedMs	integer	推理耗时（毫秒）
errorMsg	string	失败原因（成功为 null 不下发）
createdAt / completedAt	string	受理 / 完成时间；两者之差即处理耗时
resultUrl	string	success 且有产物时现签的下载链接（1 小时有效，重查换新链）
resultText	string	单笔 success 行的转写全文（与当场响应同源；任务行无此字段，任务结果走 resultUrl）
language	string	识别语言
inputName	string	输入文件名（任务形态）
durationSec	integer	音频时长秒

响应示例

            json · response
          

            {
  "total": 42, "page": 1, "pageSize": 10,
  "items": [{
    "form": "single", "status": "success",
    "inputCount": 52, "consumerCost": 0.0104,
    "createdAt": "2026-10-29T10:00:00", "completedAt": "2026-10-29T10:00:08"
  }]
}
          

04计费说明

按笔后付费：每次成功调用按实际用量从账户余额扣费，失败调用不扣费。费用明细与账户余额可在「语音识别工具」页的「历史记录」与「账户信息」页查看。

按音频实际时长计费，元 / 小时，精确到秒折算。牌价以平台实时牌价为准。异步任务按单元逐笔计费（每段音频各计一笔）。

网络中断可能发生在计费完成之后，重试同一请求会产生新的计费，请结合「调用记录」核对后再重试。