类别：provider

Model Studio Qwen ASR（非实时）

验证

mkdir -p output/alicloud-ai-audio-asr
python -m py_compile skills/ai/audio/alicloud-ai-audio-asr/scripts/transcribe_audio.py && echo "py_compile_ok" > output/alicloud-ai-audio-asr/validate.txt

通过标准：命令退出码为 0，且生成文件 output/alicloud-ai-audio-asr/validate.txt。

输出与证据

• 将转录文本及 API 响应保存至 output/alicloud-ai-audio-asr/ 目录下。
• 每次运行仅保留一条命令日志或一个示例响应。

使用 Qwen ASR 对录制音频进行离线转录（非实时），包括短音频同步调用和长音频异步任务。

关键模型名称

请严格使用以下任一模型字符串：

• qwen3-asr-flash
• qwen-audio-asr
• qwen3-asr-flash-filetrans

选型建议：

• 短/常规时长录音（同步调用）请使用 qwen3-asr-flash 或 qwen-audio-asr；
• 长音频文件转录（需走异步任务流程）请使用 qwen3-asr-flash-filetrans。

前置条件

• 安装 SDK 依赖（脚本仅使用 Python 标准库）：

python3 -m venv .venv
. .venv/bin/activate

• 在环境变量中设置 DASHSCOPE_API_KEY，或在 ~/.alibabacloud/credentials 中添加 dashscope_api_key 字段。

标准化接口（asr.transcribe）

请求参数

• audio（字符串，必填）：公开可访问的 URL 或本地文件路径。
• model（字符串，可选）：默认为 qwen3-asr-flash。
• language_hints（字符串数组，可选）：例如 zh、en。
• sample_rate（数字，可选）
• vocabulary_id（字符串，可选）
• disfluency_removal_enabled（布尔值，可选）
• timestamp_granularities（字符串数组，可选）：例如 sentence。
• async（布尔值，可选）：默认为 false（适用于同步模型）；对 qwen3-asr-flash-filetrans 默认为 true。

响应字段

• text（字符串）：标准化后的转录文本。
• task_id（字符串，可选）：仅异步提交时返回。
• status（字符串）：取值为 SUCCEEDED 或当前任务提交状态。
• raw（对象）：原始 API 响应内容。

快速开始（官方 HTTP API）

同步转录（兼容 OpenAI 协议）：

curl -sS --location 'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions' 
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" 
  --header 'Content-Type: application/json' 
  --data '{
    "model": "qwen3-asr-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_audio",
            "input_audio": {
              "data": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
            }
          }
        ]
      }
    ],
    "stream": false,
    "asr_options": {
      "enable_itn": false
    }
  }'

异步长文件转录（DashScope 协议）：

curl -sS --location 'https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription' 
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" 
  --header 'X-DashScope-Async: enable' 
  --header 'Content-Type: application/json' 
  --data '{
    "model": "qwen3-asr-flash-filetrans",
    "input": {
      "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
    }
  }'

轮询任务结果：

curl -sS --location "https://dashscope.aliyuncs.com/api/v1/tasks/" 
  --header "Authorization: Bearer $DASHSCOPE_API_KEY"

本地辅助脚本

使用内置脚本支持 URL 或本地文件输入，并可选启用异步轮询：

python skills/ai/audio/alicloud-ai-audio-asr/scripts/transcribe_audio.py 
  --audio "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3" 
  --model qwen3-asr-flash 
  --language-hints zh,en 
  --print-response

长文件模式：

python skills/ai/audio/alicloud-ai-audio-asr/scripts/transcribe_audio.py 
  --audio "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3" 
  --model qwen3-asr-flash-filetrans 
  --async 
  --wait

运维建议

• 对于本地文件，若无法提供直接可访问 URL，请使用 input_audio.data（Data URI 方式）。
• 尽量精简 language_hints，以降低识别歧义性。
• 针对异步任务，请采用 5–20 秒的轮询间隔，并设置最大重试次数保护机制。
• 将标准化输出保存至 output/alicloud-ai-audio-asr/transcripts/ 目录下。

输出路径

• 默认输出目录：output/alicloud-ai-audio-asr/transcripts/
• 可通过环境变量 OUTPUT_DIR 覆盖基础目录。

工作流

1. 确认用户意图、地域、标识符，以及操作是否为只读或变更类操作。
2. 首先执行一次最小化的只读查询，用于验证连通性与权限。
3. 使用明确参数与限定作用域执行目标操作。
4. 校验结果，并保存输出/证据文件。

参考文档

• references/api_reference.md
• references/sources.md
• 实时语音合成能力由 skills/ai/audio/alicloud-ai-audio-tts-realtime/ 提供。