venice-audio-speech

Venice TTS (/audio/speech)

POST /api/v1/audio/speech 可将文本转换为音频流或文件。兼容 OpenAI——OpenAI SDK 的 audio.speech.create() 可直接替换使用。

方法	路径	身份验证	说明
POST	/api/v1/audio/speech	Bearer 密钥或 x402 (SIWX)	JSON 请求体，返回原始音频。按输入字符计费。
POST	/api/v1/audio/voices	Bearer 密钥或 x402 (SIWX)	multipart/form-data。克隆声音 → vv_… 句柄。没有 GET /audio/voices。

适用场景

• 你需要文本转语音旁白、语音回复或 UI 音频。
• 你需要特定的语音系列（ElevenLabs、Kokoro、xAI、Qwen 3、Orpheus、Chatterbox、MiniMax、Inworld、Gemini Flash、Gradium）。
• 你希望在音频生成时以流式方式接收。
• 你需要控制受支持模型的风格／情绪，或使用克隆的声音进行合成。

如需音乐、音效和按字符计价的 ElevenLabs TTS 模型——v3、v4、v4 Turbo、Multilingual v2（异步），请参阅 venice-audio-music。如需转录（音频 → 文本），请参阅 venice-audio-transcription。

最简请求

curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-xai-v1",
    "voice": "eve",
    "input": "Hello, welcome to Venice Voice.",
    "response_format": "mp3",
    "speed": 1.0,
    "streaming": false
  }' --output hello.mp3

响应为原始音频。Content-Type 为 audio/mpeg、audio/opus、audio/aac、audio/flac、audio/wav 或 audio/pcm，具体取决于实际生成的格式。

请求架构

请求体采用严格校验——未知字段会返回 400。

字段	类型	默认值	说明
input	字符串	—	必填。 1–4096 个字符，且必须包含非空白字符。经清理后没有可朗读内容的文本（例如仅包含标记／表情符号）→ 400 "Input must contain speakable text"。
model	字符串	—	请传入此字段。 OpenAPI 架构列出了 tts-kokoro 默认值，但该默认值从未生效：省略 model 会返回 400 "model is required"。未知 ID → 404。
voice	字符串，≤ 512	模型的默认语音	语音因模型而异；使用其他模型的语音 → 400。也接受来自 POST /audio/voices 的克隆语音句柄（model 必须与创建该句柄的模型相同），并且对于 supports_custom_voice_id: true 的模型（目前为 tts-elevenlabs-turbo-v2-5），也接受原始提供商 Voice ID。
response_format	mp3 / opus / aac / flac / wav / pcm	模型的 default_format	支持情况因模型而异——请读取 model_spec.supported_formats / default_format。请求模型不支持的格式 → 400。
speed	数字	1.0	架构范围为 0.25–4.0。原样传递给 Kokoro；xAI（0.7–1.5）、ElevenLabs Turbo（0.7–1.2）和 MiniMax（0.5–2）会对其进行限制；其他模型会忽略此字段。
streaming	布尔值	false	true → 生成时以分块音频流返回。false → 返回带有 Content-Length 的缓冲文件。
language	字符串，2–32 个字符	—	可选提示；格式因模型而异（见下文）。Gemini Flash 会丢弃其地区设置列表之外的值，ElevenLabs Turbo 会丢弃长度超过 5 个字符的值；Qwen 3、MiniMax 和 xAI 会原样转发该值，如果模型拒绝该值，则返回 400 "Invalid request parameters: language"。其他模型会忽略此字段。
prompt	字符串，≤ 500	—	风格／情绪指令。Qwen 3 和 Gemini Flash 会使用此字段（作为风格指令发送）；其他模型会忽略。
temperature	数字，0–2	—	Qwen 3、Orpheus、Chatterbox HD、Gemini Flash 会使用此字段；其他模型会忽略。
top_p	数字，0–1	—	仅 Qwen 3 使用；其他模型会忽略。

各模型的 language：Qwen 3 → 全称（English、Chinese 等；默认自动检测）；xAI → ISO 639-1（en），原样转发，因此请传入有效代码（默认自动检测）；ElevenLabs Turbo → ISO 639-1（长度超过 5 个字符的值会被丢弃，较短的值会被转发）；MiniMax → 全称（作为语言增强项发送，不作校验）；Gemini Flash → 完整地区设置字符串，例如 English (US) 或 Japanese (Japan)（其他值会被丢弃）。Kokoro、Inworld、Chatterbox、Orpheus 和 Gradium 会忽略此字段。

模型

以下每个 ID 都在实时的 GET /models?type=tts 列表中。价格为 model_spec.pricing.input.usd，即每 100 万个输入字符的美元价格。

模型 ID	默认语音	格式（默认格式在前）	隐私	备注
tts-kokoro	af_sky	mp3, opus, aac, flac, wav, pcm	私有	通过语音前缀支持多语言。speed 直接传递，不限制范围。
tts-qwen3-0-6b / tts-qwen3-1-7b	Vivian	mp3	私有	prompt、temperature、top_p、language。
tts-xai-v1	eve	mp3, wav, pcm	匿名化	26 种语音，language 使用 ISO 格式。
tts-inworld-1-5-max	Craig	wav	匿名化	低延迟；所有语音均为英语。
tts-chatterbox-hd	Aurora	wav	私有	temperature。语音克隆（零样本）。
tts-orpheus	tara	wav	私有	temperature。
tts-elevenlabs-turbo-v2-5	Rachel	mp3	匿名化	接受原始 ElevenLabs 语音 ID 作为 voice。
tts-minimax-speech-02-hd	WiseWoman	mp3, pcm, flac	匿名化	language。普通密钥无法使用此模型进行克隆（见下文）。
tts-gemini-3-1-flash	Kore	mp3, opus, wav	匿名化	prompt、temperature、区域设置 language。
tts-gradium-v1	Emma	wav, pcm, opus	匿名化	语音决定语言；不支持 language 参数。

调用前务必检查 GET /models?type=tts：model_spec.voices（权威语音列表）、supported_formats、default_format、supports_custom_voice_id、privacy、pricing，以及克隆模型的 voice_cloning。/models 不会公开各模型支持的参数（prompt / temperature / top_p / language）；请参阅上表。

modelPrivacy: PRIVATE_ONLY 的密钥调用 anonymized 模型时会收到 403（PRIVATE_TEXT 密钥不受此限制）。

Voices（来自 model_spec.voices）

区分大小写。省略 voice 可使用模型的默认音色。

• Kokoro — <lang><gender>_<name>：a 表示美式英语，b 表示英式英语，z 表示中文，f 表示法语，h 表示印地语，i 表示意大利语，j 表示日语，p 表示葡萄牙语，e 表示西班牙语；f/m 表示性别。示例：af_sky、af_bella、af_heart、am_adam、am_michael、bf_emma、bm_george、ff_siwis、jf_alpha、zf_xiaoxiao、ef_dora、pm_alex（共 54 个）。
• Qwen 3 — Vivian、Serena、Ono_Anna、Sohee、Uncle_Fu、Dylan、Eric、Ryan、Aiden
• xAI — eve、ara、rex、sal、leo、altair、atlas、carina、castor、celeste、cosmo、helios、helix、iris、kepler、lumen、luna、lux、naksh、orion、perseus、rigel、sirius、ursa、zagan、zenith
• Orpheus — tara、leah、jess、mia、zoe、leo、dan、zac
• Inworld — Craig、Ashley、Olivia、Sarah、Elizabeth、Priya、Alex、Edward、Theodore、Ronald、Mark、Hades、Luna、Pixie
• Chatterbox — Aurora、Britney、Siobhan、Vicky、Blade、Carl、Cliff、Richard、Rico
• ElevenLabs Turbo — Rachel、Aria、Sarah、Laura、Charlotte、Alice、Matilda、Jessica、Lily、Roger、Charlie、George、Callum、River、Liam、Will、Eric、Chris、Brian、Daniel、Bill——或任意 ElevenLabs Voice ID
• MiniMax — WiseWoman、FriendlyPerson、InspirationalGirl、CalmWoman、LivelyGirl、LovelyGirl、SweetGirl、ExuberantGirl、DeepVoiceMan、CasualGuy、PatientMan、YoungKnight、DeterminedMan、ImposingManner、ElegantMan
• Gemini Flash — Achernar、Achird、Algenib、Algieba、Alnilam、Aoede、Autonoe、Callirrhoe、Charon、Despina、Enceladus、Erinome、Fenrir、Gacrux、Iapetus、Kore、Laomedeia、Leda、Orus、Pulcherrima、Puck、Rasalgethi、Sadachbia、Sadaltager、Schedar、Sulafat、Umbriel、Vindemiatrix、Zephyr、Zubenelgenubi
• Gradium — 英语：Emma、Kent、Eva、Jack。德语：Mia、Maximilian。西班牙语：Valentina、Sergio。法语：Elise、Leo。葡萄牙语：Alice、Davi

指定的音色不在所选模型的列表中（且不是有效的句柄 / 可用的自定义 Voice ID）→ 400。ElevenLabs Voice ID 若被提供方拒绝，也会返回 400（不收费）。

语音克隆 — POST /audio/voices

根据音频样本克隆音色，并返回一个句柄（vv_…），可将其作为 voice 传入 /audio/speech。仅支持 multipart/form-data；最大 25 MB。

curl https://api.venice.ai/api/v1/audio/voices \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "model=tts-chatterbox-hd" \
  -F "[email protected]"

{ "id": "vv_…", "model": "tts-chatterbox-hd" }

字段	说明
file	音色样本，multipart 字段为 file。通过扩展名 / MIME 和二进制签名验证。建议使用至少 5 s 的清晰语音录音（voice_cloning.min_sample_seconds；仅供参考——Venice 不会测量时长）。
model	默认为 tts-chatterbox-hd，这是唯一对常规 API 密钥开放的克隆模型。

tts-chatterbox-hd 在 /models 上通过 model_spec.voice_cloning 声明其克隆规则：

{ "mode": "zero_shot", "accepted_formats": ["mp3", "wav", "flac", "mp4"], "min_sample_seconds": 5, "retention_days": 7 }

• 零样本：不会派生音色模板；参考音频会存储并设置 TTL，每次合成调用时都会重新读取。句柄自创建起 7 天后失效，无论是否使用。
• mp4 包含 M4A。其他容器中的样本（或签名非音频的样本）会在上传前返回 400。
• 每次成功克隆都会收取固定克隆费用；合成费用则按 /audio/speech 上的字符数另行计费。

tts-minimax-speech-02-hd 也出现在 OpenAPI 规范的 model 枚举中，但常规密钥无法使用它进行克隆，会收到 403 "Voice cloning … is not available on your account"。它在 /models 上的模型规范不包含 voice_cloning 对象——可据此判断。

句柄与创建它的模型绑定。将其传入不支持克隆的模型会返回 400；与其他克隆模型配对也会失败。

流式传输

{
  "model": "tts-xai-v1",
  "voice": "eve",
  "input": "Hello, this is a long document to narrate. ...",
  "streaming": true,
  "response_format": "mp3"
}

设置 streaming: true 后，响应体是分块传输的（Transfer-Encoding: chunked）音频流，应在数据到达时解码。pcm（受支持的模型：Kokoro、xAI、MiniMax、Gradium）便于直接通过 Web Audio 播放原始音频。如果流在发送响应头前失败，会返回 500 {"error":"Stream error"}；发送响应头后失败则连接会直接关闭。

OpenAI SDK

import OpenAI from 'openai'
import fs from 'node:fs/promises'

const client = new OpenAI({
  apiKey: process.env.VENICE_API_KEY,
  baseURL: 'https://api.venice.ai/api/v1',
})

const mp3 = await client.audio.speech.create({
  model: 'tts-xai-v1',
  voice: 'eve',
  input: 'Hello from Venice.',
  response_format: 'mp3',
})

await fs.writeFile('hello.mp3', Buffer.from(await mp3.arrayBuffer()))

风格／情感（Qwen 3、Gemini Flash）

{
  "model": "tts-qwen3-1-7b",
  "voice": "Vivian",
  "input": "We did it!",
  "prompt": "Excited and energetic.",
  "temperature": 0.9,
  "top_p": 0.95
}

tts-gemini-3-1-flash 还接受 prompt（风格指令）和 temperature，但不接受 top_p。对于其他系列，表达方式取决于所选语音本身（例如，Inworld 的 Hades 与 Pixie）；prompt／temperature／top_p 会被静默忽略。

错误

代码	含义
400	缺少 model、架构错误（请求体严格校验、input 超过 4096 个字符／为空／无法朗读）、语音不适用于该模型、不支持 response_format、克隆样本无效（/audio/voices）、将句柄与非克隆模型配对使用。
401	身份验证失败。
402	余额不足。Bearer → {"error":"Insufficient USD or Diem balance…"}；如果达到密钥自身的额度上限，则为 `"API key USD
403	PRIVATE_ONLY 密钥调用 anonymized 模型、区域限制，或 /audio/voices 上尚未向你的账户开放的克隆模型。
404	未知的 model。
413	/audio/voices 样本超过 25 MB。
429	请求频率受限。
500	推理失败／流错误。
502	上游 TTS 暂时故障 — {"error":"Speech synthesis failed due to a temporary upstream error. Please retry."}（不包含 code 字段）。请采用退避策略重试。
503	模型暂时离线 — 请使用随机抖动重试。

有关响应体结构和重试策略，请参阅 venice-errors。

注意事项

• 始终发送 model — 文档所述的默认值不会生效。
• input 的硬性上限为 4096 个字符。对于较长的内容，请按句子边界拆分，并在客户端拼接音频。
• 不要假设格式为 mp3：Inworld、Chatterbox、Orpheus 和 Gradium 默认使用 wav，而且任何不在模型 supported_formats 中的 response_format 都会返回 400。请省略 response_format，或先检查 /models。
• speed 仅适用于 Kokoro（不设上限）、xAI、ElevenLabs Turbo 和 MiniMax（设有上限）。自然朗读建议保持在 0.8–1.3。
• streaming 是 Venice 专用字段，不在 OpenAI SDK 的类型定义中；可将其作为额外的请求体字段传入，或直接调用 REST 端点并读取响应体。
• 语音名称区分大小写（eve ≠ Eve，af_sky ≠ AF_SKY）。注意区分 leo（xAI／Orpheus）与 Leo（Gradium，法语）。
• Chatterbox 克隆句柄会在创建 7 天后过期。请重新克隆，不要长期保存句柄。
• Gradium 没有 language 参数 — 请为所需语言选择相应的语音。