语音转文本

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/字节上传（我们会将其暂存到私有存储桶，并在转写完成后立即删除）。限制：不支持流式（stream=true 返回 400）；文件上传最大 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) 文件上传与 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
    }
  }
}