TokenToSea开发者文档
控制台

语音识别POST

上传音频文件或提供音频 URL,返回识别文本。短音频同步返回,录音文件转写型号异步执行。

本页内容

POST https://api.tokentosea.com/v1/audio/transcriptions

把音频转成文字。推荐用 multipart/form-data 直接上传文件:平台会校验时长,按需转存到私有存储后交给厂商。部分型号也接受 JSON 中的音频 URL。

前提:全能密钥或模型密钥,账户可用余额足以覆盖按音频时长计算的预留。Python 示例需要 pip install requests,Node.js 示例需要 Node.js 18+(内置 fetch、FormData、Blob)。

支持的型号#

截至 2026-10-21,13 个型号开放本接口,以 GET /v1/models 为准。

服务商型号返回方式
千问qwen3-asr-flash、qwen-audio-3.0-asr-flash、qwen-audio-3.1-asr-flash、fun-asr-flash-2026-06-15同步
千问(录音文件转写)qwen3-asr-flash-filetrans、qwen-audio-3.0-asr-flash-filetrans、qwen-audio-3.1-asr-flash-filetrans、fun-asr、paraformer-v2、paraformer-8k-v2异步(202)
阶跃星辰step-asr-1.1异步(202)
智谱glm-asr-2512同步
MiniMaxasr-1.0同步

只支持非流式(JSON)响应。实时识别请使用 实时音频。

请求#

multipart 上传(推荐)#

字段类型必填说明
modeltext必填型号 ID
filefile必填音频文件,最大 25 MB,时长不超过 1 小时。千问型号接受 audio/wav、audio/x-wav、audio/mpeg、audio/mp4、audio/ogg、audio/flac(由文件的 Content-Type 判断);其他厂商以其文档为准
formattext可选阶跃星辰:音频格式,默认 wav。千问由文件的 Content-Type 自动判断
parameterstext(JSON)可选千问:其他厂商原生参数(例如 Paraformer 的 language_hints),以厂商文档为准
provider_optionstext(JSON)可选厂商原生扩展

一次请求只能有一个 file,最多 40 个字段。千问与阶跃星辰的文件会先转存到私有存储,再以签名链接交给厂商;智谱与 MiniMax 的文件直接以 multipart 转发。

JSON 请求#

千问与阶跃星辰型号也可以提供音频 URL,不上传文件:

参数类型必填说明
modelstring必填型号 ID
file_urlstring必填音频 URL,厂商需能公网访问。平台会下载它以测量时长(不超过 75 MiB)
formatstring部分必填千问 qwen-audio-*-asr-flash、fun-asr-flash-* 必填,例如 wav、mp3;qwen3-asr-flash 与录音文件转写型号不需要
sample_rateinteger可选千问:采样率
parametersobject可选千问:其他原生参数

智谱 glm-asr-2512 与 MiniMax asr-1.0 请使用 multipart。

响应#

同步型号返回 200 与厂商原生的识别结果(字段以厂商文档为准)。异步型号返回 202 与结果信封,完成后在 output 中给出厂商结果;千问录音文件转写的结果文件会转存到私有存储,output.data[] 中提供下载链接与 asset_id。

计费按厂商返回的音频秒数或 token 结算;平台按实测时长预留费用。

示例#

上传文件(同步)#

curl https://api.tokentosea.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F model=qwen3-asr-flash \
  -F "file=@your-audio.wav;type=audio/wav"

录音文件转写(异步)#

REQUEST_KEY="$(uuidgen)"
curl https://api.tokentosea.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -d '{"model": "paraformer-v2", "file_url": "https://example.com/meeting.mp3"}'

curl "https://api.tokentosea.com/v1/results/$REQUEST_KEY" \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY"

错误#

状态码code原因与处理
413multipart_limit_or_invalid_field文件超过 25 MB、字段过多,或文件字段名不是 file
422audio_format_not_supported千问型号无法识别上传文件的 Content-Type,请设置正确的音频 MIME
422audio_file_url_required录音文件转写型号缺少 file_url(或上传的文件)
422audio_format_required千问 qwen-audio-*-asr-flash 等以 JSON 调用时缺少 format
422media_duration_invalid音频时长无法测量或超过 1 小时
422input_media_unavailablefile_url 无法下载
422response_mode_not_verified本接口不支持流式

下一步#

    输入关键词搜索全部文档与模型。