使用 Kitta Audio 中国站 API 同步生成语音并直接获取音频二进制。

同步 HTTP

同步 TTS 用于把一段文本立即转换为语音。它适合短文本试听、服务端即时配音、后台生成少量音频等场景。请求成功后，响应体是音频二进制，不是 JSON。

长文本、批量生成或需要轮询状态的场景，请使用异步任务。

Endpoint

POST /v1/tts/speech

完整地址：

https://kittaaudio.com/api/v1/tts/speech

鉴权与请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

同步 TTS 是扣费接口。不要从浏览器端直接调用，以免泄露 API Token。

请求字段

{
  "text": "你好，这是一段 Kitta Audio 语音合成测试。",
  "voiceId": "clara",
  "model": "kitta-tts-v1",
  "speed": 1,
  "emotion": "calm"
}

字段	类型	必填	说明
`text`	string	是	待合成文本，最短 1 字符，最长 5000 字符。支持 Kitta 行内控制标签
`voiceId`	string	是	音色 ID，可从 `GET /v1/voices` 获取
`model`	string	是	TTS 模型 ID。可用值以 `GET /api/openapi.json` 返回的 schema 为准
`speed`	number	否	语速，范围 `0.5` 到 `2`，默认 `1`
`emotion`	string	否	情绪 ID。可用值以 OpenAPI schema 中的枚举为准

当前 CN TTS 请求字段保持精简：text、voiceId、model 是核心字段，speed 和 emotion 是可选控制项。不要把其它站点或旧调试工具字段当作当前 CN /v1 合同。

成功响应

成功时响应体是音频二进制：

HTTP/1.1 200 OK
Content-Type: audio/mpeg
x-kitta-request-id: req_xxx
x-kitta-credits-charged: 24

<binary audio data>

Content-Type 可能是 audio/mpeg 或 audio/wav，取决于服务端模型与响应格式。客户端应按响应头保存文件，而不是按 JSON 解析。

关键响应头：

响应头	说明
`x-kitta-request-id`	本次请求 ID，用于排查和支持定位
`x-kitta-credits-charged`	本次同步生成实际扣费

curl 示例

curl -X POST "https://kittaaudio.com/api/v1/tts/speech" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "text": "你好，这是一段同步语音合成测试。",
    "voiceId": "clara",
    "model": "kitta-tts-v1",
    "speed": 1,
    "emotion": "calm"
  }' \
  --output output.mp3

错误行为

错误响应使用嵌套结构：

{
  "error": {
    "code": "invalid_request",
    "message": "text, voiceId and model are required",
    "requestId": "req_xxx"
  }
}

状态码	场景
`400`	JSON 无效、缺少 `text` / `voiceId` / `model`、模型不支持、`speed` 超出范围
`401`	API Token 缺失或无效
`403`	当前账户无权访问指定能力、模型或音色
`402`	余额不足以覆盖本次同步生成
`500`	服务端或供应商生成失败

由于成功响应是二进制，客户端应先判断 HTTP 状态码。只有非 2xx 错误才按 JSON 错误结构解析。

计费与积分

同步 TTS 成功时会产生扣费，扣费值通过 x-kitta-credits-charged 响应头返回。客户端可以把该值写入自己的任务记录，用于和 GET /v1/usage 的 apiUsage.totalCreditsCharged 对账。

如果请求在参数校验、鉴权或额度校验阶段失败，不会返回可用音频。对 500 可以做有限次数退避重试，但要注意重复请求可能生成多份音频并产生多次扣费。

同步 HTTP

On this page