跳转到主要内容
千问云 home page
开放平台文档
非实时

Paraformer 录音文件识别 — 创建任务

提交 Paraformer 录音文件识别异步任务

POST
/services/audio/asr/transcription
cURL
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'X-DashScope-Async: enable' \
  --data '{
    "model": "paraformer-v2",
    "input": {
      "file_urls": [
        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav"
      ]
    },
    "parameters": {
      "language_hints": ["zh", "en"]
    }
  }'
{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-xxxxxxxxxxxx"
  },
  "request_id": "77ae55ae-be17-97b8-9942-xxxxxxxxxxxx"
}
请先获取 API Key 并设置为环境变量。

模型概览

模型名推荐程度适用场景
paraformer-v2推荐通用多语言识别，支持 zh/en/ja/ko/yue 等
paraformer-8k-v2推荐8 kHz 采样率音频（如电话录音）
paraformer-v1—上一代通用模型
paraformer-8k-v1—上一代 8 kHz 模型
paraformer-mtl-v1—上一代多语言模型

输入约束

  • 音频 / 视频文件必须通过 HTTP/HTTPS 公网 URL 提供，不支持 Base64 编码或本地文件路径。
  • 单次请求最多提交 100 个 URL。
  • 单个文件大小不超过 2 GB，时长不超过 12 小时。
  • 支持格式：aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv。
如需使用 OSS 内网地址（oss:// 前缀），须在请求头中添加 X-DashScope-OssResourceResolve: enable，并确保已授权 DashScope 访问对应 Bucket。临时 URL 有效期建议设置为 48 小时以上，不建议在生产环境使用临时 URL。

异步流程

  1. 调用本接口提交任务，响应中包含 task_id。
  2. 使用 task_id 轮询查询结果接口，直至 task_status 为 SUCCEEDED 或 FAILED。

识别结果说明

任务成功后，每个文件对应一个 transcription_url（有效期 24 小时），请及时下载。下载内容为 JSON 文件，以下示例展示了所有可能出现的字段（speaker_id 仅在启用说话人分离时返回）： 
{
  "file_url": "https://example.com/audio.wav",
  "properties": {
    "audio_format": "wav",
    "channels": [0],
    "original_sampling_rate": 16000,
    "original_duration_in_milliseconds": 3680
  },
  "transcripts": [
    {
      "channel_id": 0,
      "content_duration_in_milliseconds": 2640,
      "text": "北京的天气。",
      "sentences": [
        {
          "begin_time": 100,
          "end_time": 1380,
          "text": "北京的天气。",
          "words": [
            {
              "begin_time": 100,
              "end_time": 460,
              "text": "北京",
              "punctuation": "的"
            }
          ],
          "speaker_id": "spk0"
        }
      ]
    }
  ]
}
字段说明
字段类型说明
file_urlstring对应的音频文件 URL（与请求中的 URL 一致）
properties.audio_formatstring音频格式
properties.channelsarray识别的音轨索引列表
properties.original_sampling_rateinteger原始采样率（Hz）
properties.original_duration_in_millisecondsinteger音频总时长（毫秒）
transcripts[].channel_idinteger音轨索引
transcripts[].content_duration_in_millisecondsinteger有效语音时长（毫秒），不含静音片段
transcripts[].textstring完整识别文本
transcripts[].sentences[].begin_timeinteger句子开始时间（毫秒）
transcripts[].sentences[].end_timeinteger句子结束时间（毫秒）
transcripts[].sentences[].textstring句子文本
transcripts[].sentences[].words[].begin_timeinteger词开始时间（毫秒）
transcripts[].sentences[].words[].end_timeinteger词结束时间（毫秒）
transcripts[].sentences[].words[].textstring词文本
transcripts[].sentences[].words[].punctuationstring该词后的标点符号
transcripts[].sentences[].speaker_idstring说话人 ID（启用 diarization_enabled 时返回）

常见问题

提交后如何获取结果？

任务提交后返回 task_id，需轮询查询结果接口。建议每隔 1 秒查询一次，避免过于频繁。

多文件中部分失败如何处理？

当任务包含多个文件时，只要有一个文件成功，整体 task_status 即为 SUCCEEDED。需检查每个 results[].subtask_status 确认各子任务状态，失败条目会返回 code 和 message 字段。

音频文件无法下载报错

错误码 InvalidFile.DownloadFailed 表示服务无法访问音频 URL。请确认：
  • URL 是否公网可访问
  • 临时签名 URL 是否已过期
  • 文件大小是否超过 2 GB

多音轨计费说明

channel_id 中每个音轨单独计费。例如，[0, 1] 对一个文件产生两次计费。

错误码

大模型服务通用状态码请查阅错误信息。

鉴权

​
string
header
必填

千问云 API Key。详见获取 API Key。

Header 参数

​
enum<string>
必填

异步任务提交时必须设置为 enable。

可选值：enable

请求体

application/json
​
enum<string>
必填

模型名称。可用模型：paraformer-v2（推荐，支持多语言）、paraformer-8k-v2（8kHz 采样率优化）、paraformer-v1、paraformer-8k-v1、paraformer-mtl-v1（多语言）。

可选值：paraformer-v2,paraformer-8k-v2,paraformer-v1,paraformer-8k-v1,paraformer-mtl-v1
示例:paraformer-v2
​
object
必填

识别任务的输入数据。

​
object

识别参数（可选）。

响应

200-application/json
​
string

请求的唯一标识符。

示例:77ae55ae-be17-97b8-9942-xxxxxxxxxxxx
​
object