API Reference
Kitta Audio 中国站 API 中文接口参考，覆盖鉴权、端点、错误与计费口径。
API Reference
本文面向准备接入 Kitta Audio 中国站 /v1 API 的开发者。所有示例默认使用下面的 Base URL；后续端点只写路径部分。
Base URL: https://kittaaudio.com/api例如 POST /v1/tts/speech 的完整地址是：
https://kittaaudio.com/api/v1/tts/speech鉴权
中国站公开 API 使用 Bearer API Token。所有生产请求都应从服务端发起，并在请求头中携带 token：
Authorization: Bearer YOUR_API_TOKEN不要把 Token 放在浏览器、移动端客户端、URL 查询参数、公开仓库、日志或分析事件里。生成类接口会消耗账户额度，Token 泄露会直接造成用量风险。
当前 CN /v1 能力
| 能力 | 方法与路径 | 文档 |
|---|---|---|
| 同步文字转语音 | POST /v1/tts/speech | 同步 HTTP |
| 异步文字转语音 | POST /v1/tts/tasks、GET /v1/tts/tasks、GET /v1/tts/tasks/{taskId} | 异步任务 |
| 实时文字转语音 | GET /v1/tts/live | 实时 TTS |
| 异步语音转文字 | POST /v1/asr/tasks、GET /v1/asr/tasks、GET /v1/asr/tasks/{taskId} | 语音转文字 |
| 实时语音转文字 | GET /v1/asr/live | 实时 ASR |
| 图像生成 | POST /v1/images/tasks、GET /v1/images/tasks、GET /v1/images/tasks/{taskId} | 图像生成 |
| 视频生成 | POST /v1/videos/tasks、GET /v1/videos/tasks、GET /v1/videos/tasks/{taskId} | 视频生成 |
| 口型同步 | POST /v1/lip-sync/tasks、GET /v1/lip-sync/tasks、GET /v1/lip-sync/tasks/{taskId} | 口型同步 |
| 音色列表 | GET /v1/voices | 音色 |
| 用量与余额 | GET /v1/usage | 用量与余额 |
机器可读 schema：
GET /api/openapi.json请求格式
JSON 接口请发送：
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN同步 TTS 是一个例外：成功时响应体是音频二进制，而不是 JSON。其它任务类接口通常返回任务对象或任务列表。
任务模型
除同步 TTS 和只读查询外，大多数媒体能力采用异步任务模型：
POST /v1/.../tasks创建任务。- 服务端返回
taskId、status和creditsCharged。 - 客户端使用
GET /v1/.../tasks/{taskId}查询任务详情。 - 任务成功后读取
audioUrl、transcript、resultImageUrl或resultVideoUrl等结果字段。
任务列表接口通常支持 limit、offset 和 status 查询参数，状态包括 pending、processing、succeeded 和 failed。
响应与错误
成功响应随端点不同而变化：同步 TTS 返回 audio/mpeg 或 audio/wav，任务创建返回 JSON，列表接口返回 data 和 pagination。
错误响应使用嵌套结构：
{
"error": {
"code": "invalid_request",
"message": "Invalid request",
"requestId": "req_xxx"
}
}常见状态码包括 400 请求参数错误、401 鉴权失败、402 额度不足、403 权限不足、404 任务不存在，以及 500 服务端错误。排查问题时请记录 requestId。
计费与积分
生成类接口会返回或记录 creditsCharged，表示本次任务实际扣费。用量汇总可以通过 GET /v1/usage 查询。典型口径：
- 同步 TTS 成功时会通过响应头
x-kitta-credits-charged返回扣费值。 - 异步 TTS 创建时返回
creditsCharged，任务详情也会保留该字段。 - ASR、图片、视频和口型同步任务都在任务 DTO 中返回
creditsCharged。 - 只读列表、任务查询、音色列表和用量查询不创建新任务，但仍需要鉴权。
扣费接口通常会先校验额度，任务失败时以任务状态和用量记录为准。客户端不要只根据 HTTP 请求是否发出判断是否扣费，应读取响应或任务详情中的 creditsCharged。
兼容性
新客户端应优先使用本页列出的中国站 /v1 路径。旧路径迁移关系见 迁移指南。不要把不同站点或旧 Open API 路径混用到同一个 SDK 层；建议先迁移只读接口，再迁移扣费和任务创建接口。