Audio 接口 — Ling.AI

接口说明

音频模型不是一个统一的请求体。客户接入前应先通过 GET /v1/models 或模型目录确认目标模型 ID、模型类型和能力，再按对应形态调用。当前语音识别主要分为同步 input_audio、普通转写上传和异步文件 URL 转写；异步音频生成和同步 TTS 只在后台启用对应 audio 模型、Vidu operation 和 credits 计费规则后可用。

通用请求方式 POST

主要入口 /v1/chat/completions / /v1/audio/transcriptions / /v1/audio/generations / /v1/audio/speech

认证方式 Authorization / x-api-key / x-goog-api-key

先区分 ASR、音频生成与 TTS

/v1/audio/transcriptions 和 input_audio 用于语音识别，也就是音频转文字。/v1/audio/generations 用于已启用的异步音频生成模型，/v1/audio/speech 仅用于已启用的同步 TTS；当前没有公开 voice clone 路由。

请求方式

音频模型按以下三种方式接入。调用前请以当前环境返回的模型列表和后台模型配置为准；同名模型别名可能会归一到内部 canonical model 后再调度和计费。

形态	入口	请求体	适用模型	说明
同步 ASR	`/v1/chat/completions`	JSON，`messages[].content[].input_audio`	`qwen3-asr-flash` 等同步识别模型	适合短音频同步返回文本；按供应商返回的音频秒数计费
普通转写上传	`/v1/audio/transcriptions`	`multipart/form-data`，通常包含 `model` 与 `file`	真正按 multipart 转写协议接入的 `type=audio` 模型	是否支持具体字段取决于上游适配器；不要用于 `qwen3-asr-flash` 同步模型，也不要用本地 multipart 文件上传调用 Paraformer/Fun-ASR
异步文件转写	`/v1/audio/transcriptions`	JSON，必须且只能包含一个 HTTPS 公网 `file_url`	`qwen3-asr-flash-filetrans` 等文件转写模型	适合公网音频文件转写；可返回异步任务，按供应商最终用量结算

同步 ASR

qwen3-asr-flash 这类同步语音识别模型通过 Chat Completions 的 input_audio 内容块调用。当前限制为只允许一个 input_audio 内容块，且不能混入文本、图片或其他内容块。音频内容必须是 HTTPS 公网音频 URL 或音频 Base64 data URL。

curl

curl https://api.lingyuncx.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-asr-flash",
    "messages": [{
      "role": "user",
      "content": [{
        "type": "input_audio",
        "input_audio": {
          "data": "data:audio/wav;base64,BASE64_AUDIO"
        }
      }]
    }],
    "stream": false,
    "asr_options": {
      "language": "zh",
      "enable_itn": true
    }
  }'

同步 ASR 参数

参数名	类型	必填	说明
`model`	string	是	同步 ASR 模型 ID，例如 `qwen3-asr-flash`
`messages[].content[].input_audio.data`	string	是	HTTPS 公网音频 URL 或 `data:audio/...;base64,...` 音频 data URL
`stream`	boolean	否	默认 `false`；开启流式时平台会要求最终 usage 能回传用于结算
`asr_options.language`	string	否	语言代码，例如 `zh`、`en`
`asr_options.enable_itn`	boolean	否	是否启用逆文本规范化

同步 ASR 不支持的字段

enable_words、channel_id 和 corpus 只允许在异步文件转写中使用，不允许传给 qwen3-asr-flash 同步 Chat 请求。客户也不能传入 duration、audio_duration 等字段来决定计费时长。

普通转写上传

/v1/audio/transcriptions 的 multipart 形态用于真正按上传文件转写协议接入的音频模型。目标模型必须是后台已启用、客户有权限访问的 type=audio 模型，并且对应供应商绑定已联调通过。

curl

curl https://api.lingyuncx.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -F "model=your-audio-transcription-model" \
  -F "file=@/path/to/audio.wav" \
  -F "language=zh" \
  -F "response_format=json"

异步文件转写

qwen3-asr-flash-filetrans、百炼 paraformer-v2、Fun-ASR 等文件转写模型使用同一个 /v1/audio/transcriptions 路径，但请求体是 JSON。必须传且只能传一个 HTTPS 公网 file_url，可以放在顶层 file_url，也可以放在 input.file_url；Paraformer/Fun-ASR 也兼容 input.file_urls 单元素数组。

Paraformer/Fun-ASR 接入边界

百炼 paraformer-v2、paraformer-8k-v2、Fun-ASR 等录音文件识别模型要求公网 file_url 和异步任务，不是本地 multipart 文件上传。终态计费读取供应商返回的 usage.duration 或 usage.seconds，按音频秒数结算。

curl

curl https://api.lingyuncx.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "paraformer-v2",
    "input": {
      "file_urls": [
        "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
      ]
    },
    "parameters": {
      "language_hints": ["zh"],
      "enable_itn": true
    }
  }'

Fun-ASR 使用同一请求结构，只需将 model 改为 fun-asr；平台会归一为百炼录音文件识别异步任务。

json

{
  "model": "fun-asr",
  "input": {
    "file_urls": [
      "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
    ]
  },
  "parameters": {
    "language_hints": ["zh"],
    "enable_itn": true
  }
}

curl

curl https://api.lingyuncx.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-asr-flash-filetrans",
    "file_url": "https://example.com/audio.wav",
    "parameters": {
      "language": "zh",
      "enable_itn": true,
      "enable_words": true,
      "disfluency_removal_enabled": false,
      "channel_id": [0]
    }
  }'

异步音频生成

/v1/audio/generations 用于异步音频生成模型。以 Vidu 为例，后台模型会通过 operation 区分 text2audio 与 timing2audio，提交成功后返回本系统任务 ID，并通过 GET /v1/tasks/{task_id} 查询终态。计费必须以终态任务返回的 provider credits 为准，创建响应中的 credits 只能作为预估/预留证据。

curl

curl -X POST https://api.lingyuncx.com/v1/audio/generations \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-audio-generation-model",
    "prompt": "rain on metal",
    "duration": 5
  }'

异步文件转写参数

参数名	类型	必填	说明
`model`	string	是	文件转写模型 ID，例如 `qwen3-asr-flash-filetrans`
`file_url`	string	是	HTTPS 公网音频 URL；与 `input.file_url` 二选一，不可同时传
`parameters.language`	string	否	语言提示
`parameters.enable_itn`	boolean	否	是否启用逆文本规范化
`parameters.enable_words`	boolean	否	是否返回词级信息，需目标上游支持
`parameters.disfluency_removal_enabled`	boolean	否	是否开启语气词过滤，需目标上游支持
`parameters.channel_id`	array	否	声道索引数组，例如 `[0]`；计费声道数按数组长度计算
`parameters.corpus`	object	否	热词或语料参数，需目标上游支持
异步音频生成	路由已预留，模型按后台配置启用	必须通过任务轮询获取终态	终态 credits 缺失时不得按转录 token、音频时长或创建响应 credits 结算

查询异步识别结果

异步文件转写提交成功后会先返回 task_id。客户端需要轮询 GET /v1/tasks/{task_id}；查询接口的 status 会透传上游原始任务状态，例如 RUNNING、UNKNOWN、SUCCEEDED、FAILED。当响应包含 result.text 时即表示平台已保存识别文本；result.qwen_asr_filetrans_result 是平台保存完整上游转写 JSON 后返回的结果引用，不是客户需要再次请求的公网地址。

curl

curl https://api.lingyuncx.com/v1/tasks/task_xxx \
  -H "Authorization: Bearer sk-xxxxxxxx"

json

{
  "task_id": "task_xxx",
  "request_id": "audio_xxx",
  "status": "SUCCEEDED",
  "model": "fun-asr",
  "type": "audio",
  "result": {
    "text": "欢迎使用阿里云。",
    "usage": {
      "duration": "1.000000"
    },
    "qwen_asr_filetrans_result": {
      "status": "stored",
      "fetch_status": "fetched",
      "platform_result_key": "asr-result/20260605/xxxx.json",
      "byte_size": 689,
      "channel_count": 1,
      "text": "欢迎使用阿里云。",
      "text_byte_size": 24
    }
  }
}

计费说明

音频秒计费必须由服务端根据供应商返回的真实 usage 或受控估算结果结算，客户请求体中的时长字段不作为扣费依据。成功请求会进入 usage_logs，余额变化会关联到账单流水；如果供应商没有返回必需的音频用量，相关模型应按失败关闭策略处理，避免免费放行或错误扣费。

项目	说明	客户侧影响
同步 ASR	按供应商返回的 `usage.seconds` 等音频秒数字段结算，输出文本不单独按 token 计费	不要自行传时长；应关注响应和用量页是否有音频秒数
异步文件转写	提交时可按策略预留，最终以任务成功后的供应商用量结算	公网 URL 必须长期可访问到任务完成；失败任务不应按成功量扣费
多声道	`channel_id` 只在文件转写中可用，计费声道数按传入声道数量计算	只传需要识别的声道，避免不必要成本

当前边界

项目	状态	说明
语音识别	支持	按模型形态分别使用 `/v1/chat/completions` 或 `/v1/audio/transcriptions`
文字转语音	按后台模型启用	`/v1/audio/speech` 仅用于已启用的同步 TTS；当前没有公开 voice clone 路由
模型可用性	以当前环境为准	必须同时满足模型 active、API Key 有权限、供应商绑定可调度、余额和限流准入通过
上传与 URL	按模型形态限制	同步 ASR 支持音频 data URL 或 HTTPS URL；文件转写只接受 HTTPS 公网 `file_url`
异步音频生成	路由已预留，需后台启用模型	通过 `/v1/audio/generations` 创建任务；启用前确认 Provider Budget、终态 credits 结算和结果保留策略

调用前检查

建议先请求 GET /v1/models 确认模型 ID，再按模型详情页或后台配置选择调用形态。若调用 /v1/audio/transcriptions 返回模型类型错误，说明该模型不是可通过该路由调用的 type=audio 转写模型；若调用音频生成或 TTS，必须先确认后台 Vidu operation、Provider Budget 和 credits 计费规则已启用。

Audio API

接口说明

先区分 ASR、音频生成与 TTS

请求方式

同步 ASR

同步 ASR 参数

同步 ASR 不支持的字段

普通转写上传

异步文件转写

Paraformer/Fun-ASR 接入边界

异步音频生成

异步文件转写参数

查询异步识别结果

计费说明

当前边界

调用前检查

相关阅读