音频文件识别

​

提交任务

​

请求头

• Authorization string required
  认证令牌，格式为 Bearer $STEPFUN_API_KEY。
• Content-Type string required
  固定为 application/json。
• X-Trace-Id string optional
  调用方自定义 Trace ID；不传则由服务端生成。
• X-Request-Id string optional
  调用方自定义 Request ID；不传则由服务端生成。

​

请求参数

• audio object optional
  音频配置。pcm 格式必填相关参数，其他格式可由文件自动识别。

  显示 子属性

  • format string
    音频容器格式，支持 wav、mp3、pcm、ogg。
  • codec string
    编码格式，可选 raw / opus，默认 raw（pcm）。
  • rate int
    采样率；pcm 格式必填。
  • bits int
    采样位深，默认 16，当前仅支持 16bit。
  • channel int
    声道数，1（单声道）/ 2（双声道），默认 1；须与音频实际声道数一致。
  • url string
    公网可访问的音频文件地址，支持 wav、mp3、ogg、pcm，文件需小于 100MB。
• request object required
  识别配置：模型能力与输出格式。

  显示 子属性

  • model_name string required
    模型名称，例如 stepaudio-2.5-asr、step-asr-1.1。
  • enable_channel_split bool optional
    是否启用双声道分轨识别，默认 false；前提是 audio.channel 为 2。
  • show_utterances bool optional
    是否输出分句、分词及时间戳信息，默认 false。
  • enable_speaker_info bool optional
    是否启用说话人识别，默认 false；开启后每个 utterance 附带 speaker.id，需同时设置 show_utterances=true。

​

请求示例

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

​

返回

• task_id string
  任务 ID，用于后续查询结果。

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

​

查询结果

​

请求参数

• task_id string required
  提交任务时返回的任务 ID。

​

返回字段

• status string
  任务状态。排队 / 运行中时返回 RUNNING，此时响应体仅含该字段。
• duration float
  音频时长（秒），仅识别成功时返回。
• result object array
  识别结果，仅识别成功时返回。

  显示 子属性

  • text string
    整段音频的识别文本。
  • utterances object array
    分句信息，开启 show_utterances 时返回。

    显示 子属性

    • text string
      分句文本。
    • start_time int
      分句起始时间（毫秒）。
    • end_time int
      分句结束时间（毫秒）。
    • words object array
      字 / 词级信息。

      显示 子属性

      • text string
        字 / 词文本。
      • start_time int
        起始时间（毫秒）。
      • end_time int
        结束时间（毫秒）。
    • speaker object
      该句所属说话人，开启 enable_speaker_info 且 show_utterances=true 时返回。

      显示 子属性

      • id string
        说话人 ID（如 spk_1），同一任务内稳定、跨任务不保证。

​

示例

{ "status": "RUNNING" }

{
  "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_speaker_info=true：每个 utterance 附带 speaker.id，标识该句属于哪个说话人。需同时设置 show_utterances=true（speaker.id 挂在 utterance 下，无 utterances 则无处体现）。
• speaker.id（如 spk_1）同一任务内稳定、跨任务不保证。
• 可与 enable_channel_split 并存：分声道后在各声道内再区分说话人。

{
  "audio": { "format": "wav", "url": "https://example.com/meeting.wav" },
  "request": {
    "model_name": "stepaudio-2.5-asr",
    "show_utterances": true,
    "enable_speaker_info": true
  }
}

{
  "duration": 8.5,
  "result": [
    {
      "text": "你好请问有什么可以帮助您的吗在的我想咨询一下退款流程",
      "utterances": [
        { "text": "你好请问有什么可以帮助您的吗", "start_time": 0, "end_time": 1820, "speaker": { "id": "spk_1" } },
        { "text": "在的我想咨询一下退款流程", "start_time": 2000, "end_time": 4500, "speaker": { "id": "spk_2" } }
      ]
    }
  ]
}

​

错误处理

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

​

示例

curl -sS -X POST "https://api.stepfun.com/v1/audio/asr/file/submit" \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer $STEPFUN_API_KEY' \
    -d '{
        "audio": {
            "format": "wav",
            "codec": "pcm",
            "rate": 16000,
            "bits": 16,
            "channel": 1,
            "url": "https://example.com/audio.wav"
        },
        "request": {
            "model_name": "stepaudio-2.5-asr",
            "enable_channel_split": false,
            "show_utterances": true
        }
    }'

curl -sS -X POST "https://api.stepfun.com/v1/audio/asr/file/query" \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer $STEPFUN_API_KEY' \
    -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 / 单声道。
• 立体声场景如需分别识别两路说话人，可开启声道拆分。