# Qwen3-ASR-Flash FileTrans API 调用指南

## 前置条件

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

## 完整代码

```python
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"` | **必须**，异步任务模式 |

## 返回结构

```json
{
  "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 |