讓 Agent 工具將本機音訊或音訊 URL 提交給 Token Plan 語音辨識模型，並傳回转錄文字。
支援的模型
| 模型 | 能力 | 類型 |
|---|---|---|
qwen-audio-3.0-asr-flash | 語音識別 | 非即時 |
更多模型以 Token Plan 支援的模型 為準。
前提
- 已訂閱 Token Plan。個人版在 我的訂閱（個人版） 取得以
sk-sp-開頭的 API Key；團隊版在 成員管理 分配席位後取得 API Key。 - 本機已安裝 Python 3.9 或更高版本。
- 音訊為可從網際網路存取的 URL，或本機檔案。音訊長度不超過 5 分鐘，支援
wav、mp3、opus等格式，詳細限制請參閱音訊規格。
端點
POST https://token-plan.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
請求標頭使用 Authorization: Bearer $ANTHROPIC_AUTH_TOKEN。請求主體和回應欄位請參見下文。
步驟一：建立 Slash Command
將方案 API Key（以 sk-sp- 為前綴）設為環境變數 $ANTHROPIC_AUTH_TOKEN，供後續指令碼驗證使用。
在專案根目錄建立 .claude/commands/speech-to-text.md，並寫入以下內容：
呼叫 Token Plan 語音辨識 API，將音訊轉錄為文字。
音訊檔案或 URL：$ARGUMENTS
## 步驟
1. 確認輸入是本機音訊路徑或可公開存取的 URL。音訊長度不超過 5 分鐘，格式與大小限制以百煉語音辨識文件中的音訊規格為準。
2. 安裝相依套件：pip install requests
3. 使用 Bash 工具執行以下 Python 指令碼以完成辨識。指令碼會優先讀取 TOKEN_PLAN_API_KEY，其次讀取 ANTHROPIC_AUTH_TOKEN；不要顯示金鑰，也不要寫入檔案或日誌。
```python
import base64
import json
import os
import sys
from pathlib import Path
import requests
MIME_TYPES = {
"aac": "audio/aac",
"amr": "audio/amr",
"flac": "audio/flac",
"m4a": "audio/mp4",
"mp3": "audio/mpeg",
"ogg": "audio/ogg",
"opus": "audio/opus",
"wav": "audio/wav",
"webm": "audio/webm",
}
source = sys.argv[1]
key = os.environ.get("TOKEN_PLAN_API_KEY") or os.environ.get("ANTHROPIC_AUTH_TOKEN")
if not key:
raise SystemExit("Token Plan API Key not found.")
if source.startswith(("http://", "https://")):
audio_data = source
audio_format = Path(source.split("?")[0]).suffix.lstrip(".").lower() or "mp3"
else:
path = Path(source)
audio_format = path.suffix.lstrip(".").lower()
mime_type = MIME_TYPES.get(audio_format, f"audio/{audio_format}")
audio_data = f"data:{mime_type};base64,{base64.b64encode(path.read_bytes()).decode()}"
payload = {
"model": "qwen-audio-3.0-asr-flash",
"input": {
"messages": [
{
"role": "user",
"content": [
{"type": "input_audio", "input_audio": {"data": audio_data}}
],
}
]
},
"parameters": {"format": audio_format},
}
response = requests.post(
"https://token-plan.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
json=payload,
timeout=300,
)
if not response.ok:
raise SystemExit(f"{response.status_code}: {response.text}")
result = response.json()
print(result.get("output", {}).get("text") or json.dumps(result, ensure_ascii=False, indent=2))
```
4. 輸出辨識文字。需要詳細結果時，顯示傳回 JSON 中的 `sentence` 和 `words` 欄位。
步驟二：識別音訊
在 Claude Code 中輸入 /speech-to-text ./meeting.wav，或傳入音訊 URL：/speech-to-text https://example.com/audio.mp3。
請求要點
| 參數 | 說明 |
|---|---|
model | 固定為 qwen-audio-3.0-asr-flash。 |
input.messages[0].content[0].input_audio.data | 音訊 URL，或 data:audio/{format};base64,{data} 格式的 Base64 Data URI。 |
parameters.format | 必填，音訊格式，例如 wav、mp3。 |
parameters.sample_rate | 選填，音訊採樣率，例如 16000。 |
parameters.language_hints | 選填，待識別語言代碼，最多 4 個，例如 ["zh"]。 |
完整參數和回應欄位請參閱非即時語音辨識 HTTP API。
返回結果
- 辨識文字：
output.text。 - 句子級結果：
output.sentence.text、output.sentence.words（詞級時間戳）。 - 音訊時長：
usage.duration，單位秒。
其他工具
其他工具的擴充機制與設定檔路徑，請參閱接入概覽中的「工具設定檔路徑」。
限制
- Token Plan 目前提供非即時語音辨識模型
qwen-audio-3.0-asr-flash。 - 單次音訊長度不超過 5 分鐘，檔案大小和格式以音訊規格為準。
- 語音辨識使用 DashScope 協定介面，Endpoint 為
https://token-plan.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation。