autovideo/docs/qwen3_asr_filetrans_guide.md

Qwen3-ASR-Flash FileTrans API 调用指南

前置条件

pip install dashscope requests
export DASHSCOPE_API_KEY="your-key"

完整代码

import requests
import dashscope
import json
import time

API_KEY = dashscope.api_key
AUDIO_PATH = "audio.wav"

# ===== Step 1: 上传音频获取临时 URL =====
upload_resp = dashscope.Files.upload(file_path=AUDIO_PATH, purpose="file-extract")
file_id = upload_resp.output["uploaded_files"][0]["file_id"]
file_info = dashscope.Files.get(file_id=file_id)
AUDIO_URL = file_info.output["url"]

# ===== Step 2: 提交转录任务 =====
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable"       # 必须!
}
payload = {
    "model": "qwen3-asr-flash-filetrans",
    "input": {"file_url": AUDIO_URL},    # file_url 单数!
    "parameters": {
        "channel_id": [0],
        "enable_words": True,             # 字级时间戳!
        "enable_itn": False,
        "language": "zh"
    }
}
resp = requests.post(
    "https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription",
    headers=headers, json=payload
)
task_id = resp.json()["output"]["task_id"]

# ===== Step 3: 轮询结果 =====
time.sleep(2)
result = requests.get(
    f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}",
    headers={"Authorization": f"Bearer {API_KEY}"}
).json()

# ===== Step 4: 获取转录 JSON =====
tr_url = result["output"]["result"]["transcription_url"]
trans_data = requests.get(tr_url).json()

# ===== Step 5: 输出 =====
for sent in trans_data["transcripts"][0]["sentences"]:
    print(f"[{sent['begin_time']:>6}ms - {sent['end_time']:>6}ms] {sent['text']}")
    for w in sent.get("words", []):
        print(f"  [{w['begin_time']:>6}ms - {w['end_time']:>6}ms] {w['text']}{w.get('punctuation','')}")

关键参数

参数	值	说明
model	qwen3-asr-flash-filetrans	离线文件转录模型
input.file_url	string	单数，音频文件的公网 URL
parameters.enable_words	True	开启字级时间戳
parameters.language	"zh"	指定中文，提升准确率
X-DashScope-Async	"enable"	必须，异步任务模式

返回结构

{
  "transcripts": [{
    "text": "完整转录文本",
    "content_duration": 29907,
    "sentences": [{
      "begin_time": 160,
      "end_time": 1600,
      "text": "句子文本",
      "words": [
        {"begin_time": 160, "end_time": 240, "text": "字", "punctuation": ""}
      ]
    }]
  }]
}

常见错误

错误	原因	解决
MalformedURL	URL 不可访问	确保用 Files.upload 获取的 OSS URL
InvalidParameter	用了 file_urls	改为 file_url (单数)
400: max_tokens too large	用了 chat API 参数	FileTrans 不需要 max_tokens