Asr

产品简介

本服务提供音频文件中人声对应的语音内容识别为文本的能力，识别过程为异步进行。

核心特性：

支持中英文识别，暂不支持中文方言和其他语种
暂不支持热词

提交任务

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

请求说明

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

请求示例


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",
        "enable_channel_split": false,
        "show_utterances": false
    }
}

返回结果

Response Body 包含任务的核心信息：

参数名	类型	描述
task_id	string	任务 ID，用于后续查询结果。

返回示例：


{
    "task_id": "018f2f1a-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

查询结果

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

请求说明

请求方法：POST
请求路径：https://api.stepfun.com/v1/audio/asr/file/query{task_id}

请求参数

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

返回参数

参数名	层级	类型	描述	状态依赖
result	1	list	识别结果	仅当识别成功时填写
└ text	2	string	整个音频的识别结果文本	仅当识别成功时填写。
└ utterances	2	list	识别结果语音分句信息	仅当识别成功且开启show_utterances时填写。
└ text	3	string	utterance级的文本内容	仅当识别成功且开启show_utterances时填写。
└ start_time	3	int	起始时间（毫秒）	仅当识别成功且开启show_utterances时填写。
└ end_time	3	int	结束时间（毫秒）	仅当识别成功且开启show_utterances时填写。
└ words	3	list	词/字级别的文本内容
└ text	4	string	识别的文本内容
└ start_time	3	int	起始时间（毫秒）
└ end_time	3	int	结束时间（毫秒）

返回示例

示例 1：处理中

当任务处于排队/运行中时，服务端返回 200，但响应体通常为 {}（不包含 result 字段）。

示例 2：处理成功


{
    "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 状态码与错误结构以网关/服务端实现为准）。常见错误场景：

鉴权失败：未提供或提供了错误的 StepAI-UID / StepAI-KeyID
模型不支持：request.model_name 非 step-asr
限流/白名单限制：请求被限流或不在白名单
任务不存在：task_id 不存在或不属于当前 uid
任务失败：后台处理失败（下载失败/转码失败/识别失败等）

使用示例

Curl

提交任务


curl -sS -X POST "http://localhost:8000/v1/audio/asr/file/submit" \
    -H 'Content-Type: application/json' \
    -H 'StepAI-UID: 123' \
    -H 'StepAI-KeyID: 456' \
    -d '{
        "audio": {
            "format": "wav",
            "codec": "pcm",
            "rate": 16000,
            "bits": 16,
            "channel": 1,
            "url": "https://example.com/audio.wav"
        },
        "request": {
            "model_name": "step-asr",
            "enable_channel_split": false,
            "show_utterances": true
        }
    }'


{"task_id":"018f2f1a-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}

轮询查询


curl -sS -X POST "http://localhost:8000/v1/audio/asr/file/query" \
    -H 'Content-Type: application/json' \
    -H 'StepAI-UID: 123' \
    -H 'StepAI-KeyID: 456' \
    -d '{"task_id":"018f2f1a-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'

最佳实践

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

音频要求（建议）

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