语音合成（Text to Speech）
POST https://api.mafdet.ai/v1/audio/speech
使用 Gemini TTS 模型把文本合成为自然语音。端点兼容 OpenAI 规范，任何 OpenAI SDK
把 base_url 指向 https://api.mafdet.ai/v1 即可使用。响应体是音频文件本身
（二进制），不是 JSON。
| 模型 | 定位 | 文本输入 | 音频输出 |
|---|---|---|---|
gemini-2.5-flash-tts | 快速、日常朗读 | $0.60 / 1M token | $12 / 1M token |
gemini-2.5-pro-tts | 最高音质 | $1.20 / 1M token | $24 / 1M token |
两个模型均为经 Vertex AI 提供的 Gemini 2.5 preview TTS 模型。
请求字段
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | gemini-2.5-flash-tts 或 gemini-2.5-pro-tts |
input | string | 要朗读的文本，最长 5,000 字符 |
voice | string | Kore、Puck、Charon、Fenrir、Aoede 之一 |
response_format | string | 可选：wav（默认）或 pcm |
voice 必须是 Gemini 音色——OpenAI 的音色名（alloy、nova 等）会被
TTS_VOICE_NOT_ALLOWED 拒绝。
响应
原始音频字节：24 kHz、16-bit、单声道。wav 返回标准 RIFF/WAVE 文件；pcm
返回裸采样数据。
计费
TTS 按 token 双向计费：文本输入 token + 音频输出 token，按上表模型费率结算。
一句短文本通常产生 40–80 个音频输出 token（远低于 0.1 美分）。单次请求的音频输出
上限为 4,000 token。被拒绝的请求（voice 不合法、文本超长等）在调用上游前返回
400，不会计费；上游调用失败会全额释放预留金额。
curl
curl https://api.mafdet.ai/v1/audio/speech \
-H "Authorization: Bearer $MAFDET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-2.5-flash-tts",
"input": "你好，这里是 Mafdet AI。",
"voice": "Kore",
"response_format": "wav"
}' \
--output speech.wav
Python（OpenAI SDK）
from openai import OpenAI
client = OpenAI(
base_url="https://api.mafdet.ai/v1",
api_key="sk-mafdet-xxxxxxxxxxxxxxxx",
)
audio = client.audio.speech.create(
model="gemini-2.5-flash-tts",
input="你好，这里是 Mafdet AI。",
voice="Kore",
response_format="wav",
)
audio.write_to_file("speech.wav")
Node.js
const res = await fetch("https://api.mafdet.ai/v1/audio/speech", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MAFDET_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gemini-2.5-flash-tts",
input: "你好，这里是 Mafdet AI。",
voice: "Kore",
response_format: "wav",
}),
});
const buf = Buffer.from(await res.arrayBuffer());
await import("node:fs/promises").then((fs) => fs.writeFile("speech.wav", buf));
错误码
| 错误码 | 含义 |
|---|---|
TTS_INPUT_REQUIRED | input 缺失或为空 |
TTS_INPUT_TOO_LONG | input 超过 5,000 字符 |
TTS_VOICE_REQUIRED | voice 缺失 |
TTS_VOICE_NOT_ALLOWED | voice 不在模型音色白名单内（响应会回显允许的音色） |
TTS_FORMAT_NOT_ALLOWED | response_format 不是 wav / pcm |
以上错误均在调用上游前返回 400，被拒绝的请求不会产生任何费用。