語音轉文字

POST /v1/audio/transcriptions

將音訊轉寫為文字。相容 OpenAI Audio Transcriptions API——同一個端點同時服務 OpenAI Whisper / GPT-4o-transcribe 模型和 Google Gemini 模型，gateway 根據模型 ID 路由到正確的上游。可接受一個 multipart/form-data 上傳（OpenAI SDK 相容）或一個 application/json 請求主體，包含 base64 編碼的音訊。

請求主體

支援的模型

不確定用哪個模型？依需求來選

Diarization = 設定 response_format=diarized_json 以取得 segments[].speaker。預設上傳上限 25 MB（見音訊格式）。

Google 模型可透過 Gemini API 提供，或者使用 BYOK Vertex 服務帳號金鑰透過 Google Cloud Vertex AI 提供。可用性取決於為你的 workspace 啟用的通道 —— 呼叫 /v1/models 以查看你可以使用哪些模型。

支援的音訊格式

• mp3
• wav
• ogg
• flac
• m4a

對於 multipart 上傳，格式由檔名副檔名推斷。對於 base64（JSON）請求，請設定 input_audio.format 。最大上傳大小： 25 MB。

回應格式

該 response_format 可接受的取值取決於模型。 json 是所有模型的預設值（回傳 { text, usage }); text 回傳原始轉寫字串。

• whisper-1 — json, text, verbose_json
• gpt-4o-transcribe, gpt-4o-mini-transcribe — json, text
• chirp-3, chirp-2, seed-asr-bigmodel, qwen3-asr-flash, fun-asr-flash — json, text
• gpt-4o-transcribe-diarize, chirp-3, seed-asr-bigmodel, fun-asr, fun-asr-mtl — also diarized_json （帶語者標註的分段；見下文）

verbose_json （分段時間戳）僅限 whisper-1；

語者分離

設定 response_format=diarized_json 即可取得帶說話者標籤的分段——回應會新增一個 segments 陣列，其中每一項都帶有 speaker 標籤以及 start/end 時間戳（秒）。支援 gpt-4o-transcribe-diarize（OpenAI）、chirp-3（Google）、seed-asr-bigmodel（BytePlus——中文與長錄音性價比最佳）以及 fun-asr / fun-asr-mtl（Alibaba——離線錄音檔，接受 URL 或檔案）。其他模型會忽略 diarized_json 並回傳純文字；chirp-2 會拒絕它（請用 chirp-3）。

說話者標籤由提供商原生給出（例如 chirp-3 與 seed-asr 用 "0"/"1"，gpt-4o-transcribe-diarize 用 "A"/"B"）；它們用於區分不同說話者，但並非穩定的真實身分。在 gpt-4o-transcribe-diarize 上，你可以傳入 known_speaker_names 來引導標註。

# Chinese meeting, cheapest diarization (BytePlus seed-asr):
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seed-asr-bigmodel",
    "input_audio": { "url": "https://your-bucket/signed/meeting.wav", "language": "zh" },
    "response_format": "diarized_json"
  }'

# English / highest quality (Google chirp-3, <=60 s per request):
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=chirp-3 \
  -F file=@call.wav \
  -F response_format=diarized_json

範例回應

{
  "task": "transcribe",
  "text": "喂 你好 我这边是客服 有什么可以帮您",
  "duration": 6.2,
  "segments": [
    { "id": 0, "start": 0.10, "end": 0.90, "speaker": "0", "text": "喂 你好" },
    { "id": 1, "start": 1.20, "end": 6.20, "speaker": "1", "text": "我这边是客服 有什么可以帮您" }
  ]
}

請求範例（multipart）

curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=gpt-4o-transcribe \
  -F file=@meeting.mp3 \
  -F response_format=json \
  -F language=en

範例請求（base64 JSON）

POST /v1/audio/transcriptions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "model": "gpt-4o-transcribe",
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10I...",
    "format": "wav"
  },
  "response_format": "json",
  "language": "en"
}

範例 — 離線 ASR（seed-asr-bigmodel）

seed-asr-bigmodel（BytePlus 海外離線 ASR）接受兩種互斥的輸入：一個可抓取的 input_audio.url（建議使用 — 你自己的限時簽章物件儲存 URL；音訊絕不會經過我們的儲存空間），或直接上傳 file／位元組（我們會暫存於私有 bucket，並在轉錄完成後立即刪除）。限制：不支援串流（stream=true 會回傳 400）；file 上傳上限為 25 MB（較大的錄音請改用 URL）；單一請求的處理上限約為 20 分鐘，因此超長音訊請先分段。依音訊時長計費（$0.002/min）。

# ① Quick test — replace ONLY YOUR_API_KEY and run it (uses our hosted sample audio).
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seed-asr-bigmodel",
    "input_audio": {
      "url": "https://synthorai-asr-sample-360831509259.s3.us-west-1.amazonaws.com/seed-asr-sample.wav",
      "language": "zh"
    }
  }'
# → {"text":"..."}

# ② Your own audio file (<=25 MB) — replace key + file path.
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=seed-asr-bigmodel \
  -F language=zh \
  -F file=@/path/to/your-audio.wav

# ③ Your own signed URL (recommended for large files / privacy) — replace key + URL.
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seed-asr-bigmodel","input_audio":{"url":"https://your-bucket/signed/meeting.wav","language":"zh"}}'

注意事項／陷阱：(1) language 為選填 — 常用值有 zh（國語）、yue-CN（粵語）、en-US；省略即自動偵測。(2) 使用 input_audio.url 時，該 URL 必須能被轉錄服務公開抓取 — 私有／內網／需驗證的 URL 會失敗；建議使用限時簽章（預簽章）的物件儲存 URL。(3) file 上傳與 URL 互斥，請擇一使用。(4) 沒有可辨識語音的音訊（靜音）會回傳 200 並附帶空字串 {"text":""}，而非錯誤。

範例 — OpenAI Python SDK

該端點與 OpenAI 相容，因此官方 OpenAI SDK 可直接透過覆寫以下設定使用 base_url. 對 whisper-1、gpt-4o-transcribe 以及任何 Gemini 轉寫模型的用法相同 —— 只需更改 model.

from openai import OpenAI

client = OpenAI(
    base_url="https://synthorai.io/v1",
    api_key="YOUR_API_KEY",
)

with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="gpt-4o-transcribe",
        file=f,
        language="en",
        # prompt="Synthorai, BYOK, transcribe",   # optional vocabulary hint
        response_format="json",
    )

print(result.text)
# Token-level usage on gpt-4o-*:
if getattr(result, "usage", None):
    print(result.usage)

範例 — OpenAI Node.js SDK

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({
  baseURL: "https://synthorai.io/v1",
  apiKey: process.env.SYNTHORAI_API_KEY,
});

const result = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: fs.createReadStream("meeting.mp3"),
  language: "en",
  response_format: "json",
});

console.log(result.text);

串流（SSE）

設定 stream=true 於 gpt-4o-transcribe, gpt-4o-mini-transcribe，或任何 Gemini 轉寫模型，以在音訊解碼時接收增量事件。回應的 Content-Type 為 text/event-stream 和事件以以下內容結束 data: [DONE]。whisper-1 不支援串流（若設定則回傳 400 stream=true).

對於 gpt-4o-transcribe，你會看到的事件類型：

data: {"type":"transcript.text.delta","delta":"Hello "}

data: {"type":"transcript.text.delta","delta":"world."}

data: {"type":"transcript.text.done","text":"Hello world."}

data: {"type":"usage","usage":{"type":"tokens","input_tokens":689,"output_tokens":287,"total_tokens":976,"input_token_details":{"audio_tokens":689,"text_tokens":0,"cached_tokens":0}}}

data: [DONE]

Gemini streaming 使用相同的 SSE 事件名稱，且閘道發出相同的規範化 usage 物件，記錄於以下章節 範例回應—— 在 OpenAI 和 Gemini 之間完全一致 —— 因此用戶端程式碼可在不同 provider 之間移植。最終的 usage 事件始終攜帶完整的 input_token_details 明細，用於準確的按音訊計費。

錯誤

所有錯誤都遵循 OpenAI 的封裝格式： { error: { message, type, code, param? } }. 常見情況：

• 400 model_not_found ——模型在該 workspace 的通道中不具備轉寫能力。
• 400 byok_strict_no_key ——workspace 處於嚴格 BYOK 模式 (byok_fallback_to_pool=false) 且沒有為解析出的供應商設定 vault key。
• 400 content_policy_violation ——該 prompt 欄位觸發了護欄規則（例如 BYOK key 洩漏）。
• 402 quota_exceeded ——預估成本超出 workspace 剩餘配額。BYOK 不受此限制。
• 408 ——請求主體未在伺服器讀取逾時內完成上傳。在透過慢速連線傳送大音訊時常見；請重試或傳送更小的檔案。
• 413 ——音訊超出 25 MB 上限。
• 502 upstream_error ——上游網路故障或模型供應商回傳非 2xx 回應。

範例回應

{
  "text": "Thanks for joining today's call. Let's get started.",
  "usage": {
    "type": "tokens",
    "input_tokens": 689,
    "output_tokens": 287,
    "total_tokens": 976,
    "input_token_details": {
      "audio_tokens": 689,
      "text_tokens": 0,
      "cached_tokens": 0
    }
  }
}