语音合成与转写
两者都遵循 OpenAI 的 Audio API，所以 OpenAI SDK 里的 client.audio.speech 和 client.audio.transcriptions 改一下基础地址就能用。下面两个示例都是真实的文件，发布前我们都会实际运行一遍。
语音合成
# pip install openai
# Text to speech. `voice` is required and its names belong to the model:
# af_heart is one of hexgrad/kokoro-82m's voices.
import os
from openai import OpenAI
client = OpenAI(
base_url=os.getenv("OCEANTOKEN_BASE_URL", "https://api.oceantoken.ai/v1"),
api_key=os.environ["OCEANTOKEN_API_KEY"],
)
with client.audio.speech.with_streaming_response.create(
model="hexgrad/kokoro-82m",
voice="af_heart",
input="Welcome aboard. The ferry leaves at nine.",
response_format="mp3",
) as response:
response.stream_to_file("speech.mp3")
print("saved speech.mp3")
POST /v1/audio/speech 直接返回音频。
| 字段 | 作用 |
|---|---|
model | 语音合成模型的 ID。 |
input | 要朗读的文字。 |
voice | 必填。 模型自己的音色名称，见音色。 |
response_format | mp3 最稳妥，下表中除特别注明的以外都支持。url 返回一个链接而不是音频（见下文）。 |
speed、instructions | 语速（0.25 到 4）和语气说明（比如"平静、慢一点"），适用于支持它们的模型。 |
语音合成按 input 的字符数计费（计费方式）。请发送 Idempotency-Key，这样超时后的重试不会把同一段音频生成（并扣费）两次（错误）。
音色
音色名称由模型决定。不带 voice 的请求会以 400 被拒绝，模型不认识的名称会导致请求失败。第二列的音色已在线上服务实测可用（2026-09-26）：
| 模型 | 实测可用的音色 | 发布方列出的其他音色 |
|---|---|---|
hexgrad/kokoro-82m | af_heart | af_bella、am_michael、bf_emma、bm_george |
deepgram/aura-2 | aura-2-thalia-en | aura-2-andromeda-en、aura-2-apollo-en、aura-2-asteria-en、aura-2-helena-en、aura-2-orion-en、aura-2-zeus-en |
canopylabs/orpheus-3b-0.1-ft | tara | leah、jess、leo、dan、mia、zac、zoe |
sesame/csm-1b | conversational_a | conversational_b |
x-ai/grok-voice-tts-1.0 | Ara | Rex、Sal、Eve、Leo |
microsoft/mai-voice-2 | en-US-Jasper:MAI-Voice-1 | |
fish-audio/s1、fish-audio/s2-pro、fish-audio/s2.1-pro、fish-audio/s2.1-pro-free:free | alloy | |
google/gemini-3.1-flash-tts-preview | Kore（不要发送 response_format；它返回 WAV） | Puck、Charon、Fenrir、Aoede、Leda、Orus、Zephyr |
其他语音合成模型，请使用其发布方文档中的音色名称。
改为返回链接
设置 "response_format": "url" 时，返回的是带有 MP3 链接的 JSON，而不是音频字节，方便直接交给浏览器或下一个请求使用：
{"url": "https://...", "content_type": "audio/mpeg", "bytes": 48213, "usage": {"input_characters": 41}}
请在 24 小时内下载。这段音频也会出现在控制台的生成记录里。
语音转写
# pip install openai
# Audio file to text. This transcribes speech.mp3, the file the text-to-speech
# sample writes; use any mp3, m4a, wav or webm of your own.
import os
from openai import OpenAI
client = OpenAI(
base_url=os.getenv("OCEANTOKEN_BASE_URL", "https://api.oceantoken.ai/v1"),
api_key=os.environ["OCEANTOKEN_API_KEY"],
)
with open("speech.mp3", "rb") as audio:
transcript = client.audio.transcriptions.create(model="openai/gpt-4o-mini-transcribe", file=audio)
print(transcript.text)
POST /v1/audio/transcriptions 接收 multipart 上传：
| 字段 | 作用 |
|---|---|
file | 音频文件：mp3、m4a、wav、webm 等常见格式。 |
model | 语音转写模型的 ID。 |
language | 音频的语言，用 ISO-639-1 代码，比如 en 或 zh。可选；知道语言时填上能提高准确率。 |
prompt | 可能出现的人名、专有名词的写法。可选。 |
response_format | json（默认）返回 {"text": "..."}；text 返回纯文本；verbose_json 额外返回带时间戳的分段；srt 和 vtt 返回字幕。各模型支持的格式不同。 |
用 curl 发送：
curl https://api.oceantoken.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
-F model="openai/gpt-4o-mini-transcribe" \
-F file=@meeting.mp3
- 请求最大 10 MB（限制）。更长的录音请切分或压缩：64 kbit/s 的 MP3，10 MB 大约能装 20 分钟。
- 语音转写按音频分钟数计费（计费方式）。
- 文件必须上传；用 URL 代替文件不会被下载。
下一步
- 视频：给视频配上旁白。
- 所有语音合成和语音转写模型的价格见 oceantoken.ai。