Profile 与 Usage

早期文档中的 Profile 接口已不属于当前 CN /v1 公开合同。中国站现在通过 GET /v1/usage 查询账户余额、API 用量和近期积分流水。

如果你的旧客户端依赖“Profile”概念，请把它迁移为 Usage 查询：用 GET /v1/usage 判断账户余额、任务统计和最近消费记录。

何时使用

验证 API Token 是否能访问当前账户数据。
查询账户总余额、订阅余额和长期余额。
查看 API 任务数量、成功失败数量和累计扣费。
在提交生成任务前做额度展示或后台预检。
排查 402 额度不足时确认最近用量。

Usage 是只读查询，不会创建任务，也不会扣减积分。

Endpoint

GET /v1/usage

完整地址：

https://kittaaudio.com/api/v1/usage

鉴权与请求头

Authorization: Bearer YOUR_API_TOKEN

curl 示例：

curl -X GET "https://kittaaudio.com/api/v1/usage?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

查询参数

参数	类型	说明
`limit`	integer	返回近期流水数量，范围 1 到 100，默认 20
`offset`	integer	分页偏移量，默认 0
`since`	datetime	仅统计指定时间之后的 API 用量，使用 ISO 时间字符串

响应

成功响应：

{
  "balance": 1200,
  "subscriptionBalance": 900,
  "longLivedBalance": 300,
  "totalPurchased": 2000,
  "totalConsumed": 800,
  "apiUsage": {
    "totalTasks": 12,
    "succeededTasks": 11,
    "failedTasks": 1,
    "pendingTasks": 0,
    "processingTasks": 0,
    "totalCreditsCharged": 600,
    "totalCharacters": 3200,
    "generatedAudioBytes": 1450000,
    "lastTaskAt": "2026-07-01T08:00:00.000Z",
    "byEndpoint": []
  },
  "recentTransactions": []
}

字段说明：

字段	说明
`balance`	当前总余额
`subscriptionBalance`	订阅周期内余额
`longLivedBalance`	长期有效余额
`totalPurchased`	累计购买或获得的积分
`totalConsumed`	累计消耗积分
`apiUsage.totalTasks`	API 任务总数
`apiUsage.totalCreditsCharged`	API 任务累计扣费
`apiUsage.byEndpoint`	按端点聚合的任务、字符和扣费统计
`recentTransactions`	近期积分流水

错误行为

错误响应使用嵌套结构：

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

状态码	场景
`401`	API Token 缺失或无效
`403`	当前 token 无权读取账户用量
`500`	用量查询或聚合失败

计费与积分

Usage 查询不消耗积分，也不会改变余额。它只读取已经发生的任务扣费和积分流水。如果你看到余额变化，请优先检查同一时间段内是否有 TTS、ASR、图片、视频或口型同步任务。

迁移提示

旧 Profile 通常只返回用户 ID、层级和单个 API quota 字段；当前 Usage 返回更完整的余额和任务统计。迁移 SDK 时不要再寻找 Profile 专用端点，而是把账户预检、余额展示和对账统一接到 GET /v1/usage。

Profile 与 Usage

On this page