TTS API 参考

Shisa TTS HTTP API 提供两个端点：一个用于生成语音，一个用于列出可用声音。两者均使用标准 Bearer 令牌进行身份验证。如需通过 WebSocket 接收流式音频，请参阅 WebSocket 流式。

Authorization: Bearer YOUR_API_KEY

端点

生成语音

POST https://api.shisa.ai/tts

将文本转换为语音音频。以请求的格式返回二进制音频数据。

列出声音

GET https://api.shisa.ai/tts/voices

返回一个包含voices数组的对象，其中列出当前所有活动声音、元数据、支持的格式、采样率和流式传输能力。目录请参阅声音。

请求参数

POST /tts 端点的参数，以 JSON 主体形式发送：

参数	类型	必填	描述
`voice_id`	string	必填	要使用的声音 UUID。可从 `GET /tts/voices` 获取可用 ID。
`text`	string	必填	要转换为语音的文本。默认上限：5,000个Unicode字符。
`format`	string	必填	输出音频格式。必须是所选声音支持的格式。`mp3`、`wav`、`ogg`、`pcm`、`flac` 之一。
`stream`	boolean	可选	为`true`时，以分块流形式返回音频用于实时播放。声音必须为`streaming: true`，并且所选格式必须支持在该提供商上流式传输。默认为`false`。
`sample_rate`	integer	可选	省略或设为`0`时使用默认24,000 Hz。仅对列出多个采样率的声音设置非零值。Qwen 后端声音使用`ogg`时不接受采样率覆盖。
`temperature`	number	可选	提供商特定的变化控制，目前对Qwen后端声音有意义（Qwen默认值：`0.5`）。其他声音请省略。

响应

POST /tts — 二进制音频

成功时，API返回带有适当Content-Type头的原始二进制音频数据（MP3为audio/mpeg）。将响应体直接保存到文件：

# The response is binary audio data — save directly to file
curl -s -X POST "https://api.shisa.ai/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice_id": "61ba1141-60aa-4bc3-a3b3-be1ec20700b3", "format": "mp3", "text": "テスト"}' \
  --output speech.mp3

GET /tts/voices — JSON

返回一个包含可用声音对象数组的对象：

{
  "voices": [
    {
      "id": "e3362c0a-7677-4cd8-b122-91fb093305c9",
      "description": "Young male Japanese voice...",
      "language": "Japanese & English",
      "gender": "Male",
      "formats": ["mp3", "ogg", "pcm"],
      "sample_rates": [8000, 16000, 22050, 24000, 32000, 44100, 48000],
      "streaming": true
    }
  ]
}

声音对象字段：

字段	类型	描述
`id`	string (uuid)	在请求中用作 `voice_id` 的 UUID。
`description`	string	人类可读的声音描述。
`language`	string	支持的语言。
`gender`	string	声音性别（Male、Female、Neutral）。
`formats`	array	支持的输出音频格式。
`sample_rates`	array	支持的输出采样率（Hz）。
`streaming`	boolean	声音的提供商是否至少支持一种格式的实时流式传输；这不表示`formats`中的每个值都可流式传输。

错误处理

错误以下列格式的 JSON 返回：

{
  "context": ["..."],
  "code": 104,
  "name": "ErrAuthenticationFailed",
  "error": "Authentication error: Invalid token"
}

错误代码

状态	原因	解决方案
`400`	参数缺失或无效	检查 `voice_id`、`text` 和 `format` 字段。
`400`	声音不支持的格式	使用声音 `formats` 数组中列出的格式。
`400`	提供商与格式的组合不支持流式传输	将`stream`设为`false`，或选择可流式传输的格式。
`400`	不支持的采样率	省略`sample_rate`，或选择声音支持的可配置采样率。
`400`	文本超过配置上限	缩短文本；默认上限为5,000个字符。
`401`	API 密钥无效或缺失	检查您的 `Authorization: Bearer` 头。
`403`	服务访问被拒绝	该密钥不能使用所选声音背后的提供商。
`404`	TTS服务/提供商未注册	检查服务可用性或联系支持。
`429`	超出速率限制	使用指数退避等待后重试。
`500`	内部服务器错误	重试请求或联系技术支持。

注意

当请求的format不在所选声音的formats数组中时，也会返回400。此外，streaming: true并不保证每种支持的格式都能流式传输；不受支持的提供商/格式组合在stream: true时会返回400。

后续步骤

在快速开始中逐步完成您的第一个请求。
在声音目录中浏览可用声音。
在价格中了解用量的计费方式。

端点​

生成语​音​

列​出声​音​

请​求​参数​

响​应​

POST /tts — 二​进制​音频​

GET /tts/voices — JSON​

错误​处理​

错误代​码​

后续​步​骤​

端点