跳到主要内容

文本转语音 WebSocket

GET 
wss://api.knoxstudio.ai/v1/text-to-speech/:voice_id/stream-input

面向分块文本（例如 LLM 流）的 WebSocket TTS。全文已知时请使用 HTTP 合成。GET 和 POST 都接受升级。普通 HTTP 返回 400。仅流式 output_format（无 WAV）。按发送的字符计费。

请求​

路径参数​

名称类型必填描述
voice_idString是ElevenLabs 音色 ID。

查询参数​

名称类型必填描述
model_idString否默认 eleven_multilingual_v2。
output_formatString否仅流式格式：mp3_22050_32, mp3_24000_48, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192, pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_32000, pcm_44100, pcm_48000, ulaw_8000, alaw_8000, opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192。
enable_loggingBoolean否默认 true。
apply_text_normalizationString否auto、on 或 off。
inactivity_timeoutInteger否空闲后关闭套接字的秒数。
sync_alignmentBoolean否在音频消息中包含对齐信息。
auto_modeBoolean否自动触发生成。

可以使用请求头时不要把 API key 放进查询字符串。浏览器原生 WebSocket 不能设头，可用 ?authorization= / ?api_key=。Knox 也接受 xi-api-key。JSON 消息体中的凭证会被剥离。

请求头​

名称类型必填描述
AuthorizationString是Bearer <token> Knox API key。也接受 xi-api-key。
UpgradeString是必须为 websocket。

客户端消息​

发送 JSON 文本帧：

{
  "text": "第一块文本 ",
  "try_trigger_generation": true,
  "voice_settings": { "stability": 0.5, "similarity_boost": 0.75 }
}

发送 "text": ""（通常配合 try_trigger_generation: true）冲刷剩余音频。冲刷空文本后再关闭套接字以结束生成。

第一条消息上的 model_id 和 voice_settings 会覆盖查询默认值。不要在负载中发送 xi-api-key。

服务端消息​

{
  "audio": "<base64>",
  "isFinal": false,
  "normalizedAlignment": {},
  "alignment": {}
}

isFinal: true 表示已冲刷文本的音频结束。

示例​

const ws = new WebSocket(
  "wss://api.knoxstudio.ai/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM/stream-input?model_id=eleven_flash_v2_5&output_format=mp3_44100_128"
);
ws.onopen = () => {
  ws.send(JSON.stringify({ text: "你好，这里是 Knox。 ", try_trigger_generation: true }));
  ws.send(JSON.stringify({ text: "", try_trigger_generation: true }));
};

在允许自定义头的环境用 Authorization 传递 Knox key，或使用 xi-api-key。

错误响应​

校验失败返回 HTTP 422：

{
  "detail": [
    {
      "loc": ["body", "field"],
      "msg": "…",
      "type": "value_error"
    }
  ]
}

其他错误使用 { "detail": "message" }。

状态何时
400未携带 Upgrade: websocket 访问 WebSocket 路径。
401缺少或无效的 API key。
402余额不足。
403Token 无权使用该模型。
404资源不存在。
422校验错误。
429超出速率限制。
500服务器内部错误。