Whisper-1 API：完成第一次音訊轉錄

第一次呼叫 Whisper-1 API 需要音訊檔案、明確的模型 ID 與輸出格式。在 SeedRouter 上傳錄音後，保存傳回的任務 ID，等任務完成再下載逐字稿。先使用一段內容熟悉的短錄音，會更容易發現漏字或不尋常的拼字。

本指南採用 SeedRouter 的非同步契約，無法直接當作 OpenAI SDK 的同步範例使用。Whisper-1 模型頁 提供 Playground 與即時價格；API 參考文件 列出每個欄位及尚待完成的相容性檢查。^[1]

準備一段錄音

請使用你有權處理的語音。短 WAV 或 MP3 適合做為起點。目前上傳上限為 26,214,400 位元組；檔案必須包含可讀取且時長可測量的音訊。將文字檔的副檔名改為 .mp3，並不會讓它變成有效音訊。參考文件區分了文件記載的九種輸入格式，以及已通過實際檢查的格式。^[1]

下方錄音是為本教學製作的原創英文合成語音。封面呈現它的波形。封面引用的句子來自錄音腳本，並非準確率聲明。

下載 10.31 秒範例。腳本原文是：「This is a sample recording for an audio transcription tutorial. Our meeting starts at nine thirty on Monday. Please bring the project notes and review the final checklist before we begin.」

將 API 金鑰放在伺服器端環境變數。不要放入公開網頁、行動應用程式套件或共用螢幕截圖。下方 Python 範例使用 requests，並從環境變數讀取 SEEDROUTER_API_KEY。

只提交一次 Whisper-1 API 請求

第一次請求選擇 json，就能讀取下載結果的 text 欄位，不必處理字幕時間碼。multipart 的 file 部分必須包含實際位元組；以 URL 作為欄位值不等於上傳檔案。讓用戶端設定 multipart 內容類型與 boundary。^[1]

將程式保存為 transcribe.py。它會在 POST 前寫入提交標記，並在請求被接受後保存任務 ID。再次執行時會讀取既有任務。若 POST 結果不確定，這個標記可防止程式意外建立重複請求。

import json
import os
from pathlib import Path

import requests

base = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
state = Path("whisper-task.json")
audio = Path("recording.wav")

if not state.exists():
    if not 0 < audio.stat().st_size <= 26_214_400:
        raise ValueError("Choose a nonempty recording within the upload limit")
    with state.open("x") as marker:
        json.dump({"status": "submission_unconfirmed"}, marker)
    with audio.open("rb") as recording:
        response = requests.post(
            f"{base}/audio/transcriptions",
            headers=headers,
            files={"file": (audio.name, recording, "audio/wav")},
            data={"model": "whisper-1", "response_format": "json"},
            timeout=180,
            allow_redirects=False,
        )
    response.raise_for_status()
    accepted = response.json()
    task_id = accepted.get("id")
    if not isinstance(task_id, str) or not task_id.startswith("task_"):
        raise RuntimeError("Submission could not be confirmed; check task history")
    state.write_text(json.dumps({"id": task_id}), encoding="utf-8")

saved = json.loads(state.read_text(encoding="utf-8"))
if "id" not in saved:
    raise RuntimeError("Check task history before submitting another recording")

response = requests.get(
    f"{base}/tasks/{saved['id']}", headers=headers, timeout=30,
    allow_redirects=False,
)
response.raise_for_status()
task = response.json()
print(task["status"])
if task["status"] == "completed":
    result = requests.get(task["output"]["url"], timeout=60)
    result.raise_for_status()
    print(result.json()["text"])
elif task["status"] == "failed":
    print(task["error"])

執行 python transcribe.py。如果印出 processing，等待幾秒後再次執行相同指令。它會讀取已保存的 ID，而非再次上傳。每次有意處理新的錄音時，請使用獨立狀態檔。僅憑用戶端逾時，無法判定任務失敗。

讀取完成的逐字稿

接受請求的回應包含 id、model、status 與 created_at。完成後會增加 output.url 與 output.format。該 URL 指向結果檔，不是需要再次付費請求的媒體生成任務。使用 GET 即可下載結果。^[1]

一邊聽錄音，一邊閱讀文字。將文字用作字幕或精確引用前，請核對姓名、數字與句子邊界。逐字稿是口述內容的初稿，即使有時間戳記仍需校對。

2026 年 10 月 19 日的本地端對端檢查，完成了全部五種轉錄格式與一次英文輸入翻譯。這些檢查驗證受測錄音的交付與計費行為，不代表已確立準確率百分比或跨語言翻譯品質。

選擇文字、時間戳記或字幕

需要詞級時間戳記時，傳送 response_format=verbose_json，並加入名稱為 timestamp_granularities[]、值為 word 的可重複 multipart 欄位。若兩者都需要，再加入值為 segment 的部分。在 Python requests 中，以 (name, value) 配對組成的串列表示重複欄位。每個時間戳記都以秒為單位。^[2]

詞級時間戳記與說話者標籤是不同輸出。只要求片段，不會讓 Whisper-1 將會議轉成附說話者標籤的逐字稿。它也不會串流傳回部分文字：此模型會忽略 stream。使用已驗證流程時，請省略 chunking_strategy；明確選擇 auto 未通過實際相容性檢查。^[1]

視需要加入語言與拼字上下文

選填的 language=en 告訴轉錄請求輸入是英文。希望自動偵測時，請省略。產品名稱容易聽錯時，可在 prompt 中使用與音訊相同的語言，提供正確拼字。Whisper 提示詞提供上下文，不像聊天指令能可靠地要求特定版面。^[3]

上下文應與音檔相關。Whisper 只使用其分詞器最後 224 個 token。傳送長文件，不代表錄音可以套用無限長的詞彙表；字元計數也無法可靠地取代這項 token 規則。

翻譯成英文時，將端點改為 /audio/translations。它的五個請求欄位為 file、model、prompt、response_format 與 temperature。翻譯輸出英文，沒有目標語言選擇器。若提供提示詞，請使用英文。^[4]

擴充工作流程前先確認費用

下方即時表格使用實測音訊時長。同一段錄音的逐字稿變長，不會增加時長費用。每個檔案的時長先無條件進位至整秒，再換算為音訊計量單位。API 參考文件提供精確算法，Playground 能讀取錄音時長後會顯示預估費用。失敗的請求不收費。

大量處理檔案前，先驗證一段具代表性的錄音並檢查結果。保存每段錄音的任務 ID，連線中斷後便能讀取既有狀態來復原。加入字幕或測試較少的格式組合前，請閱讀完整參數參考。

第一次整合的常見問題

可以直接使用 OpenAI Python SDK 範例嗎？

不行。multipart 輸入欄位雖然熟悉，但 SeedRouter 傳回非同步任務 ID。預期 POST 回應含有 text 的同步用戶端需要調整。本文範例明確區分提交與讀取結果。

為什麼 JSON 結果沒有詞級時間戳記？

預設 json 格式以文字為主。請同時要求 verbose_json 與 word 時間戳記粒度。只有片段時間資訊，不會為每個詞建立一筆項目。

逾時後應該再傳送一次 POST 嗎？

先檢查已保存的任務 ID 或任務紀錄。請求可能已被接受，只是回應遺失。讀取既有任務可避免為相同錄音建立另一個請求。

Whisper-1 即將停用嗎？

OpenAI 已宣布，其自有 API 上的 Whisper 將於 2027 年 2 月 26 日關閉。這項公告不代表本服務的關閉日期。建立新整合時，請將生命週期公告納入維護清單。^[5]

來源

[1] SeedRouter Whisper-1 API 參考文件與驗證狀態，檢查日期：2026 年 10 月 19 日。

[2] OpenAI 轉錄參考文件。

[3] OpenAI Whisper 提示詞指南。

[4] OpenAI 翻譯參考文件。

[5] OpenAI 轉錄模型淘汰公告。