认证

Kitta Audio 中国站 /v1 API 使用 Bearer API Token 鉴权。Token 代表你的账户和可用额度，所有生产流量都应从后端服务或受控的 serverless 函数发出。

Authorization: Bearer YOUR_API_TOKEN

何时使用

只要请求进入 https://kittaaudio.com/api/v1/...，就应携带 Authorization 请求头。包括只读接口，例如 GET /v1/usage、GET /v1/voices，也包括扣费接口，例如 POST /v1/tts/speech、POST /v1/asr/tasks 和 POST /v1/lip-sync/tasks。

当前 CN /v1 合同不要求在请求体里传 token。新系统应统一使用请求头，避免密钥出现在任务载荷、错误日志或前端状态中。

创建与管理 Token

登录后在开发者设置中创建和管理 Token：

/zh-CN/app/developer

建议按应用或环境拆分 token，例如 prod-worker、staging-api、local-dev。如果某个系统泄露，只需要撤销对应 token，而不用影响其它生产应用。

请求头示例

JSON 任务接口：

POST /v1/tts/tasks HTTP/1.1
Host: kittaaudio.com
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

同步 TTS 接口：

POST /v1/tts/speech HTTP/1.1
Host: kittaaudio.com
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

只读查询接口：

GET /v1/usage HTTP/1.1
Host: kittaaudio.com
Authorization: Bearer YOUR_API_TOKEN

安全规则

不要把 API Token 放到浏览器 JavaScript、移动端客户端、公开仓库、截图、日志或分析事件中。
不要在 URL 查询参数中传 token；URL 经常会被代理、浏览器历史和监控系统记录。
本地开发建议使用环境变量，例如 KITTA_AUDIO_API_TOKEN，并确保 .env 不提交到 Git。
生产环境中请使用部署平台的 Secret 管理能力。
怀疑泄露时立即撤销旧 token，创建新 token，并排查近期用量。

常见错误

状态码	含义	处理方式
`401`	Token 缺失、格式不正确或已失效	检查 `Authorization: Bearer ...`，确认没有多余空格或使用了错误环境的 token
`403`	Token 有效但当前账户无权访问该能力或资源	检查账号权限、产品开通状态和资源归属
`402`	额度或积分不足	查询 `GET /v1/usage`，确认余额和 API 用量
`500`	服务端或供应商错误	记录 `error.requestId` 后重试或联系支持

错误响应通常包含 requestId：

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API token",
    "requestId": "req_xxx"
  }
}

联系支持时请提供 requestId、调用时间、方法、路径和你的内部任务 ID。不要发送完整 API Token。

计费说明

鉴权本身不扣费，只读接口通常不消耗积分。扣费发生在具体生成或转写接口中，例如 TTS、ASR、图片、视频和口型同步。鉴权失败、参数校验失败、额度不足等请求不会返回成功任务，也不会产生可用结果。

认证