ElevenLabs 音频

方法	路径	用途	模型广场协议
`POST`	`/v1/text-to-speech/{voice_id}`	语音合成，返回完整音频	ElevenLabs Text to Speech
`POST`	`/v1/text-to-speech/{voice_id}/stream`	语音合成，边生成边返回音频	ElevenLabs Text to Speech
`POST`	`/v1/text-to-speech/{voice_id}/with-timestamps`	语音合成，附带字符级时间戳	ElevenLabs Text to Speech with Timestamps
`POST`	`/v1/text-to-speech/{voice_id}/stream/with-timestamps`	流式返回音频与时间戳	ElevenLabs Text to Speech with Timestamps
`GET`	`/v1/text-to-speech/{voice_id}/stream-input`	WebSocket：边输入文本边返回音频	ElevenLabs Text to Speech WebSocket

路径、请求体与响应体都按 ElevenLabs 官方 Text to Speech 与 stream-input 文档。同一个模型不一定开放全部入口：以模型广场标注的协议为准（见上表最后一列），未开放时 HTTP 返回 400 model_protocol_not_offered，WebSocket 握手返回 403。

HTTP 语音合成

bash

curl "https://api.modelgo.com/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "<model>",
    "text": "你好，欢迎使用 ModelGo。",
    "voice_settings": { "stability": 0.5, "similarity_boost": 0.75 }
  }' \
  --output speech.mp3

参数	位置	说明
`voice_id`	路径	ElevenLabs 音色 ID
`output_format`	Query	输出格式，如 `mp3_44100_128`、`pcm_16000`，取值同官方
`model_id`	Body，必填	平台逻辑模型名。官方缺省时会用 `eleven_multilingual_v2`，这里必须显式填写
`text`	Body，必填	要合成的文本
其他官方字段	Body	`voice_settings`、`language_code`、`seed`、`previous_text`、`next_text`、`apply_text_normalization` 等，按官方定义原样转发

optimize_streaming_latency、enable_logging 等 Query 参数会被接受但不生效。

不带时间戳的两个入口直接返回音频字节（如 audio/mpeg），/stream 边生成边返回。
/with-timestamps 返回 JSON：音频在 audio_base64（Base64），alignment / normalized_alignment 给出每个字符的 characters、character_start_times_seconds、character_end_times_seconds：

json

{
  "audio_base64": "<base64 mp3 bytes>",
  "alignment": {
    "characters": ["你", "好"],
    "character_start_times_seconds": [0.0, 0.21],
    "character_end_times_seconds": [0.21, 0.42]
  },
  "normalized_alignment": { "characters": ["你", "好"], "character_start_times_seconds": [0.0, 0.21], "character_end_times_seconds": [0.21, 0.42] }
}

/stream/with-timestamps 返回连续的多个上述 JSON 对象（不是 SSE），按对象逐个解析即可。
计费按 text 的 Unicode 字符数计量，与输出格式、音频时长无关；单价见控制台「模型列表」。
鉴权使用 Authorization: Bearer <API Key>（也接受 x-api-key）。HTTP 入口暂不接受 xi-api-key 请求头，使用官方 SDK 时需改为传 Authorization。错误使用平台统一的错误格式，见错误码与限流。

WebSocket 流式输入

适合 LLM 一边生成文本、一边转语音的场景：客户端分段发送文本，服务端分段返回音频。

项	值
完整地址	`wss://api.modelgo.com/v1/text-to-speech/{voice_id}/stream-input?model_id=<逻辑模型名>`
Query	`model_id`（必填）；可选 `output_format`、`language_code`、`sync_alignment`、`apply_text_normalization`、`seed`，其他官方参数会被忽略
鉴权	握手时带 `xi-api-key` 或 `Authorization: Bearer <API Key>` 请求头；或按官方浏览器用法在第一条消息里带 `xi_api_key`

客户端消息（JSON 文本帧）：

json

{"text": " ", "voice_settings": {"stability": 0.5, "similarity_boost": 0.8}}
{"text": "你好，这是流式输入测试。 ", "flush": true}
{"text": ""}

第一条消息初始化会话，text 通常为一个空格，可带 voice_settings（只有 stability、similarity_boost 生效）；
之后每条消息追加一段文本，flush: true 要求立即合成已收到的文本；
发送 {"text": ""} 表示输入结束，服务端发完剩余音频后返回 {"isFinal": true} 并以 1000 正常关闭。
generation_config、try_trigger_generation、发音词典等字段会被忽略。

服务端消息：

json

{"audio": "<base64 音频片段>", "isFinal": null, "normalizedAlignment": {…}, "alignment": {…}}
{"isFinal": true}

audio 可能为空字符串，跳过即可。

握手错误（升级为 WebSocket 之前，以 HTTP 状态码返回，body 形如 {"error":{"type":"invalid_request_error","code":"…","message":"…"}}）：

HTTP	含义
400	缺少 `model_id` 或 `voice_id`，或不是 WebSocket 升级请求
401	未携带或无效的 API Key
402	余额或预算不足
403	无权调用该模型，或该模型未开放 WebSocket 入口
404	模型不存在或没有可用路由
503	暂无可用的服务商，可稍后重试

使用首条消息鉴权时，连接已经升级，上述拒绝改为下发一条错误消息后关闭（5xx 类关闭码为 1011，其余为 1008）。

会话中的错误：先下发一条 {"message": "…", "error": "<错误码>", "code": <关闭码>}，再按该关闭码关闭连接：

情况	`error`	关闭码
单连接累计文本超过 5000 字符	`max_characters_exceeded`	1008
单连接达到 10 分钟上限	`max_session_duration`	1008
消息不是 JSON 文本帧	`invalid_message`	1003 / 1007
首条消息超时未到（请求头鉴权 20 秒，首条消息鉴权 10 秒）	`initial_message_timeout`	1008
连接服务商失败	`provider_unavailable`	1011

计费：按本次连接实际送去合成的文本 Unicode 字符数计量（初始化用的空格、结束标记，以及不带 flush 的纯空白保活消息不计）。建连时按 5000 字符预占额度，断开后按实际字符结算；一个字符都没送出时不扣费。连接空闲时由平台向服务商保活，客户端无需额外发送保活消息。