跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
产品简介

本服务提供音频文件中人声对应的语音内容识别为文本的能力，识别过程为异步进行。 核心特性：
  • 支持中英文识别，暂不支持中文方言和其他语种
  • 暂不支持热词

​
提交任务

用于创建一个新的语音识别任务。

​
请求说明

  • 请求方法：POST
  • 请求地址：https://api.stepfun.com/v1/audio/asr/file/submit
  • Content-Type：application/json

​
请求头

参数名必填类型说明
Authorization是string认证 Token，格式：Bearer {API_KEY}
X-Trace-Id否string调用方自定义 trace id；不传则服务端生成
X-Request-Id否string调用方自定义 request id；不传则服务端生成

​
请求参数 (Body)

字段说明层级类型必填备注
audio音频流配置1dict可选PCM 格式必填，其他格式使用识别的结果
└ format音频容器格式2string音频文件的容器格式。由文件上传服务识别。支持格式：wav, mp3, pcm, ogg
└ codec音频编码格式2string可选：raw / opus，默认为 raw (pcm)。
└ rate音频采样率2intPCM 必填
└ bits音频采样点位数2int默认为 16，暂只支持 16bits。
└ url访问的公网文件地址2string支持格式: wav、mp3、ogg 和 pcm。文件大小限制：小于 100MB
└ channel音频声道数2int1 (单声道) / 2 (双声道)，默认为 1。必须准确填写音频文件的实际声道数。
request识别请求配置1dict是核心层：用于配置模型能力和输出格式。
└ model_name模型名称2string是例如：step-asr-1.1。
└ enable_channel_split启用双声道识别2bool默认为 false。前提条件：音频声道数 channel 必须为 2。
└ show_utterances输出语音停顿、分句、分词信息及时间戳信息2bool

​
请求示例

POST https://api.stepfun.com/v1/audio/asr/file/submit
Content-Type: application/json
Authorization: Bearer sk-xxxxxxxxxxxx

{
    "audio": {
        "format": "wav",
        "codec": "pcm",
        "rate": 16000,
        "bits": 16,
        "channel": 1,
        "url": "https://example.com/audio.wav"
    },
    "request": {
        "model_name": "step-asr-1.1",
        "enable_channel_split": false,
        "show_utterances": false
    }
}

​
返回结果

Response Body 包含任务的核心信息：
参数名类型描述
task_idstring任务 ID，用于后续查询结果。
返回示例： 
{
    "task_id": "018f2f1a-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

​
查询结果

根据任务 ID 查询识别进度或获取最终结果。

​
请求说明

  • 请求方法：POST
  • 请求路径：https://api.stepfun.com/v1/audio/asr/file/query
  • Content-Type：application/json

​
请求参数

参数名必选类型描述
task_id是string提交任务时返回的任务 ID。

​
返回参数

参数名层级类型描述状态依赖
duration1float音频时长（秒）仅当识别成功时填写
result1list识别结果仅当识别成功时填写
└ text2string整个音频的识别结果文本仅当识别成功时填写。
└ utterances2list识别结果语音分句信息仅当识别成功且开启 show_utterances 时填写。
   └ text3stringutterance 级的文本内容仅当识别成功且开启 show_utterances 时填写。
   └ start_time3int起始时间（毫秒）仅当识别成功且开启 show_utterances 时填写。
   └ end_time3int结束时间（毫秒）仅当识别成功且开启 show_utterances 时填写。
   └ words3list词/字级别的文本内容
      └ text4string识别的文本内容
      └ start_time3int起始时间（毫秒）
      └ end_time3int结束时间（毫秒）

​
返回示例

示例 1：处理中 当任务处于排队/运行中时，服务端返回 200，响应体仅包含 status 字段： 
{"status":"RUNNING"}
示例 2：处理成功 
{
    "duration": 5.901375,
    "result": [
        {
            "text": "识别出的完整文本",
            "utterances": [
                {
                    "text": "你好",
                    "start_time": 0,
                    "end_time": 500,
                    "words": [
                        {"text": "你", "start_time": 0, "end_time": 200},
                        {"text": "好", "start_time": 200, "end_time": 500}
                    ]
                }
            ]
        }
    ]
}
声道拆分说明 当 enable_channel_split=true 且输入为立体声时，服务端会拆分为多个声道分别识别，result 数组长度可能为 2，每个元素对应一个声道的输出。

​
错误处理

接口会以标准 JSON 错误响应返回失败原因（HTTP 状态码与错误结构以网关/服务端实现为准）。常见错误场景：
  • 鉴权失败：未提供或提供了错误的 Authorization 头（Bearer {API_KEY}）
  • 模型不支持：request.model_name 非 step-asr-1.1
  • 限流/白名单限制：请求被限流或不在白名单
  • 任务不存在：task_id 不存在或不属于当前 uid
  • 任务失败：后台处理失败（下载失败/转码失败/识别失败等）

​
使用示例

​
Curl

​
提交任务

curl -sS -X POST "https://api.stepfun.com/v1/audio/asr/file/submit" \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer sk-xxxxxxxxxxxx' \
    -d '{
        "audio": {
            "format": "wav",
            "codec": "pcm",
            "rate": 16000,
            "bits": 16,
            "channel": 1,
            "url": "https://example.com/audio.wav"
        },
        "request": {
            "model_name": "step-asr-1.1",
            "enable_channel_split": false,
            "show_utterances": true
        }
    }'
返回： 
{"task_id":"018f2f1a-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}

​
轮询查询

curl -sS -X POST "https://api.stepfun.com/v1/audio/asr/file/query" \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer sk-xxxxxxxxxxxx' \
    -d '{"task_id":"018f2f1a-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'

​
最佳实践

  1. 轮询节流：建议 1s~3s 轮询一次，避免过于频繁造成限流
  2. 超时控制：客户端设置总体超时，避免无限等待
  3. URL 可达性：确保 audio.url 可被服务端直接下载（建议 HTTPS、可公网访问或在服务网络可访问）
  4. 结果粒度：
    • 只需要整段文本：show_utterances=false
    • 需要时间戳/字幕对齐：show_utterances=true
  5. 声道拆分：双人对话/左右声道分别录制场景可开启 enable_channel_split=true

​
音频要求（建议）

  • 优先使用清晰语音、较少背景噪音的录音
  • 若可控制录制格式，建议：16kHz / 16bit / mono
  • 立体声场景如需分别识别两路说话人，可启用声道拆分