RESTful API - 千问云

使用指南：教程、代码示例和模型详情请参见录音文件转写。该服务包含两个 API：任务提交和任务查询。先提交任务，再轮询查询 API 获取结果。

限制条件

该服务不支持上传本地文件或 Base64 编码的音频。您必须提供通过 HTTP 或 HTTPS 协议公开访问的文件 URL，例如 https://your-domain.com/file.mp3。通过 file_urls 参数指定 URL，单次请求最多支持 100 个 URL。

音频格式：aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv

音频格式存在众多变体，API 无法保证所有格式都能正确处理。请先测试您的文件以验证结果。

音频采样率：不限
文件大小和时长：最大 2 GB，最长 12 小时。超出限制的文件需先预处理，参见使用 FFmpeg 预处理音频文件。
批量大小：单次请求最多 100 个文件 URL。
支持语言： fun-asr 支持中文、英文和日语。fun-asr-mtl 系列支持多种语言，详见支持的语言。
前端调用：不支持从前端直接调用该 API，请使用后端代理。

任务提交 API

基本信息

项目	说明
描述	提交语音识别任务。
URL	`https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription`
请求方式	POST
请求头	见下文
请求体	见下文

请求头：

Authorization: Bearer $DASHSCOPE_API_KEY
Content-Type: application/json
X-DashScope-Async: enable

必须包含 X-DashScope-Async: enable 请求头。

请求体（包含所有请求参数，可选字段可省略）：

{
  "model": "fun-asr",
  "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": {
    "vocabulary_id": "vocab-Xxxx",
    "channel_id": [0],
    "diarization_enabled": false,
    "speaker_count": 2
  }
}

请求参数

点击查看请求示例

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":"fun-asr","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":{"channel_id":[0]}}'

参数	类型	默认值	是否必填	说明
model	string	-	是	模型名称。参见语音识别模型。
file_urls	array[string]	-	是	音频或视频文件 URL 列表（HTTP/HTTPS），单次请求最多 100 个 URL。
vocabulary_id	string	-	否	热词 ID，将热词应用于当前任务，默认禁用。参见自定义热词。
channel_id	array[integer]	[0]	否	多音轨文件中要识别的音轨索引，从 0 开始。例如 `[0]` 识别第一音轨，`[0, 1]` 识别前两个音轨。默认识别第一音轨。
special_word_filter	string	-	否	配置敏感词处理方式。参见敏感词过滤详情。
diarization_enabled	boolean	false	否	启用说话人分离。仅支持单声道音频。启用后，结果中包含 `speaker_id` 字段以区分不同说话人。参见识别结果说明。
speaker_count	integer	-	否	说话人数量参考值（2 到 100）。仅在 `diarization_enabled` 为 `true` 时生效。算法会尽量输出指定数量的说话人，但不保证准确。默认自动检测。
language_hints	array[string]	["zh", "en"]	否	识别语言代码。未设置时模型自动检测语言。参见支持的语言。

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

敏感词过滤详情

未设置 special_word_filter 时，内置过滤器将匹配的词替换为等长的星号（*）。设置后，可使用以下策略：

替换为 *：将匹配的词替换为等长的星号。
过滤删除：从结果中移除匹配的词。

值必须为 JSON 字符串：

{
  "filter_with_signed": {
    "word_list": ["test"]
  },
  "filter_with_empty": {
    "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}

字段说明：

filter_with_signed
- 类型：object。是否必填：否。
- 将匹配的词替换为等长的星号。
- 示例："Help me test this piece of code" 变为 "Help me **** this piece of code"。
- 内部字段：word_list -- 要替换的词的字符串数组。
filter_with_empty
- 类型：object。是否必填：否。
- 从结果中移除匹配的词。
- 示例："Is the game about to start?" 变为 "Is the game about to ?"。
- 内部字段：word_list -- 要移除的词的字符串数组。
system_reserved_filter
- 类型：Boolean。是否必填：否。默认值：true。
- 启用系统预设的敏感词规则。设为 true 时，匹配千问云敏感词列表的词会被替换为等长的星号。

支持的语言

各模型支持的语言代码：

fun-asr, fun-asr-2025-11-07：
- zh：中文
- en：英文
- ja：日语
fun-asr-2025-08-25：
- zh：中文
- en：英文
fun-asr-mtl, fun-asr-mtl-2025-08-25：
- zh：中文
- en：英文
- ja：日语
- ko：韩语
- vi：越南语
- id：印尼语
- th：泰语
- ms：马来语
- tl：菲律宾语
- ar：阿拉伯语
- hi：印地语
- bg：保加利亚语
- hr：克罗地亚语
- cs：捷克语
- da：丹麦语
- nl：荷兰语
- et：爱沙尼亚语
- fi：芬兰语
- el：希腊语
- hu：匈牙利语
- ga：爱尔兰语
- lv：拉脱维亚语
- lt：立陶宛语
- mt：马耳他语
- pl：波兰语
- pt：葡萄牙语
- ro：罗马尼亚语
- sk：斯洛伐克语
- sl：斯洛文尼亚语
- sv：瑞典语

响应参数

点击查看响应示例

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942-************"
}

参数	类型	说明
task_status	string	任务状态：`PENDING`、`RUNNING`、`SUCCEEDED` 或 `FAILED`。
task_id	string	任务 ID，用于任务查询 API 获取结果。
request_id	string	请求 ID。

任务查询 API

基本信息

项目	说明
描述	查询语音识别任务的状态和结果。
URL	`https://dashscope.aliyuncs.com/api/v1/tasks/\{task_id\}`
请求方式	GET
请求头	见下文
请求体	无

请求头：

Authorization: Bearer $DASHSCOPE_API_KEY

请求参数

点击查看请求示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY"

参数	类型	默认值	是否必填	说明
task_id	string	-	是	任务提交 API 返回的任务 ID。

响应参数

多子任务场景：只要有任何一个子任务成功，整体状态即为 SUCCEEDED。请检查 subtask_status 了解各子任务的实际结果。

点击查看响应示例（成功）

{
  "request_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
    "task_id": "f86ec806-4d73-485f-a24f-************",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "end_time": "2024-09-12 15:11:40.903",
    "results": [
      {
        "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/3bdf7689-b598-409d-806a-121cff5e4a31-1.json?Expires=1726211500&OSSAccessKeyId=yourOSSAccessKeyId&Signature=Fj%2BaF%2FH0Kayj3w3My2ECBeP****%3D",
        "subtask_status": "SUCCEEDED"
      },
      {
        "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=yourOSSAccessKeyId&Signature=v5Owy5qoAfT7mzGmQgH0g8C****%3D",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 2,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}

点击查看响应示例（部分失败）

code 字段包含错误码，message 字段包含错误信息。这些字段仅在出错时出现。

{
  "request_id": "a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "output": {
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
      {
        "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20241216/xxxx",
        "subtask_status": "SUCCEEDED"
      },
      {
        "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav",
        "code": "InvalidFile.DownloadFailed",
        "message": "The audio file cannot be downloaded.",
        "subtask_status": "FAILED"
      }
    ],
    "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 1,
      "FAILED": 1
    }
  }
}

点击查看响应示例（进行中）

{
  "request_id": "b3c4d5e6-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "output": {
    "task_id": "9d1f2a3b-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "task_status": "RUNNING",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 0,
      "FAILED": 0
    }
  }
}

参数	类型	说明
task_id	string	任务 ID。
task_status	string	任务状态。
subtask_status	string	子任务状态。
file_url	string	已处理文件的 URL。
transcription_url	string	识别结果链接，有效期 24 小时。过期后无法查询任务或下载结果。结果为 JSON 文件，可通过 HTTP 下载或读取。参见识别结果说明。
submit_time	string	任务提交时间。
scheduled_time	string	任务调度时间。
end_time	string	任务结束时间。
task_metrics	object	任务指标：包含 `TOTAL`（总数）、`SUCCEEDED`（成功数）和 `FAILED`（失败数）。
usage	object	用量信息。`duration` 为总时长，单位为秒。

识别结果说明

识别结果为 JSON 文件。

点击查看识别结果示例

以下为启用说话人分离（diarization_enabled=true）时的识别结果示例：

{
  "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
  "properties": {
    "audio_format": "pcm_s16le",
    "channels": [0],
    "original_sampling_rate": 16000,
    "original_duration_in_milliseconds": 3834
  },
  "transcripts": [
    {
      "channel_id": 0,
      "content_duration_in_milliseconds": 3720,
      "text": "Hello world, this is Alibaba Speech Lab.",
      "sentences": [
        {
          "begin_time": 100,
          "end_time": 3820,
          "text": "Hello world, this is Alibaba Speech Lab.",
          "sentence_id": 1,
          "speaker_id": 0,
          "words": [
            {
              "begin_time": 100,
              "end_time": 596,
              "text": "Hello ",
              "punctuation": ""
            },
            {
              "begin_time": 596,
              "end_time": 844,
              "text": "world",
              "punctuation": ", "
            }
          ]
        }
      ]
    }
  ]
}

speaker_id 字段仅在启用说话人分离时出现。为简洁起见，其他词条目已省略。

主要参数：

参数	类型	说明
audio_format	string	源文件的音频格式。
channels	array[integer]	音轨索引。单音轨返回 `[0]`，双音轨返回 `[0, 1]`，以此类推。
original_sampling_rate	integer	采样率（Hz）。
original_duration_in_milliseconds	integer	原始音频时长（毫秒）。
channel_id	integer	转写的音轨索引，从 0 开始。
content_duration_in_milliseconds	integer	音轨中语音内容的时长（毫秒）。
text	string	转写文本（段落级或词级，取决于上下文）。
sentences	array	句级转写结果。
sentence_id	integer	句子序号，从 1 开始。
words	array	词级转写结果。
begin_time	integer	起始时间戳（毫秒）。
end_time	integer	结束时间戳（毫秒）。
speaker_id	integer	说话人索引，从 0 开始。仅在启用说话人分离时出现。
punctuation	string	词后的预测标点符号（如有）。

计费仅基于语音片段，而非文件总时长。非语音片段不计费。由于语音检测使用 AI 模型，计费时长可能与预期内容时长略有差异。

​限制条件

​任务提交 API

​基本信息

​请求参数

​敏感词过滤详情

​支持的语言

​响应参数

​任务查询 API

​基本信息

​请求参数

​响应参数

​识别结果说明

限制条件

任务提交 API

基本信息

请求参数

敏感词过滤详情

支持的语言

响应参数

任务查询 API

基本信息

请求参数

响应参数

识别结果说明