个人访问令牌

个人访问令牌是用于自动化管理 BeatAPI 账户的凭据。它继承你的账户权限，脚本可以用它读取账户数据，例如每个任务或每次文本请求花了多少钱。调用模型、提交任务和工作流仍然使用 API 密钥。

个人访问令牌与 API 密钥的区别

	个人访问令牌	API 密钥
前缀	`nap_`	`sk-`
用途	账户自动化，例如 `GET /v1/account/usage/records`	模型、任务和工作流请求
数量	每个账户同一时间只有一个有效令牌	按需创建多个
限制	没有独立的模型、IP 或消费额度限制	每个密钥可单独设置模型、IP 和消费额度限制
有效期	永不过期；重新生成或撤销后才失效	每个密钥可单独设置有效期

创建、重新生成或撤销

登录控制台，打开账户安全。
点击创建个人令牌，完成安全验证。
复制令牌。完整令牌仅展示这一次，关闭窗口后会从页面中清除。
把它作为密钥保存在运行自动化程序的环境中，例如 BEATAPI_PERSONAL_TOKEN。

重新生成个人令牌会签发新令牌，旧令牌立即失效。撤销个人令牌会删除令牌，使用它的工具立即失去访问权限。两项操作都需要安全验证。请只在可信服务器上保存令牌，不要放进浏览器代码、移动应用或共享代码仓库。

可调用的接口

接口	用途
`GET /v1/account/usage/records`	按时间倒序列出账户的计费请求
`GET /v1/account/usage/records/{id}`	按任务 ID 或请求 ID 读取一条记录
`GET /v1/usage`	账户汇总与明细，见快速指南

请求时发送 Authorization: Bearer <token>。这些接口需要 usage:read 权限，个人令牌默认包含该权限。两个用量记录接口用 API 密钥调用会返回 403 forbidden；GET /v1/usage 既接受 API 密钥也接受个人令牌，返回同一份汇总。之后会有更多账户接口支持个人令牌。

核对单个任务

保存创建任务时返回的 data.id，然后查询：

curl https://api.beatapi.io/v1/account/usage/records/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN"

{
  "data": {
    "object": "usage_record",
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "type": "image",
    "model": "seedream-5-pro",
    "task_id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "request_id": "202610290330051234567893f9a1c2eXy7Kp2Qd",
    "api_key": { "id": "1287", "title": "production", "key_prefix": "sk-Ab3d" },
    "status": "succeeded",
    "created_at": 1793244605,
    "currency": "USD",
    "credits_charged": 0.06,
    "credits_refunded": 0,
    "usage": { "images": 2 }
  }
}

文本请求请使用响应头 X-BeatAPI-Request-Id 中的请求 ID。如果文本响应体的 id 是 chatcmpl-<request ID>，也可以直接用这个值查询。用任务创建请求的请求 ID 查询，返回的是与任务 ID 相同的记录。

列出用量记录

curl -G https://api.beatapi.io/v1/account/usage/records \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \
  --data-urlencode "start=2026-10-01T00:00:00Z" \
  --data-urlencode "end=2026-11-01T00:00:00Z" \
  --data-urlencode "limit=100"

{
  "data": {
    "object": "list",
    "data": [
      {
        "object": "usage_record",
        "id": "20261029041512987654321b3f9a1c2eQm8Rt4Lw",
        "type": "text",
        "model": "deepseek-v4.1-flash",
        "request_id": "20261029041512987654321b3f9a1c2eQm8Rt4Lw",
        "api_key": { "id": "1287", "title": "production", "key_prefix": "sk-Ab3d" },
        "status": "succeeded",
        "created_at": 1793247312,
        "currency": "USD",
        "credits_charged": 0.002468,
        "credits_refunded": 0,
        "usage": { "input_tokens": 1200, "output_tokens": 350, "cached_tokens": 1024 }
      }
    ],
    "has_more": true,
    "next_cursor": "eyJ0IjoxNzkzMjQ3MzEyLCJpIjo5ODc2NTQzMn0"
  }
}

参数	说明
`start`	包含的最早 `created_at`。Unix 秒或 RFC 3339，例如 `2026-10-01T00:00:00Z`
`end`	上界（不含），格式同上
`model`	对外模型 ID，例如 `seedream-5-pro`
`type`	`text`、`image`、`video`、`workflow`、`data`、`realtime` 或 `other`
`api_key_id`	API 密钥的数字 ID，与 `api_key.id` 相同
`limit`	每页条数，1–100，默认 20
`cursor`	上一页返回的 `next_cursor`

has_more 为 true 时，带上 cursor 请求下一页。未知参数、超出 1–100 的 limit 或毫秒时间戳会返回 400 bad_request，不会被忽略。

用量记录字段

字段	说明
`object`	`usage_record`
`id`	任务为任务 ID，其他为请求 ID
`type`	`text`、`image`、`video`、`workflow`、`data`、`realtime` 或 `other`
`model`	对外模型 ID
`task_id`	任务记录才有
`request_id`	产生这条记录的请求 ID（已知时返回）
`api_key`	付费的 API 密钥的 `id`、`title` 和 `key_prefix`；控制台试玩产生的用量为 `null`
`status`	`queued`、`processing`、`succeeded`、`failed`，整笔费用已退回时为 `refunded`
`created_at`	Unix 秒
`currency`	`USD`
`credits_charged`	实际支付的美元金额，已计入折扣和结算差额；最多六位小数
`credits_refunded`	退回余额的美元金额
`usage`	计费用量：文本为 `input_tokens`、`output_tokens`、`cached_tokens` 和 `cache_write_tokens`；媒体为 `images`、`seconds` 和 `resolution`

任务的金额与 GET /v1/tasks/{task_id} 返回的 usage.credits_charged 和 usage.credits_refunded 一致。任务结算金额高于或低于预扣金额时，记录显示结算后的总额。只能读取自己账户的记录：其他账户的 ID 返回 404 not_found。

错误

状态码	`code`	场景
`400`	`bad_request`	查询参数无效
`401`	`unauthorized`	令牌缺失、无效或已过期
`403`	`forbidden`	用 API 密钥调用了用量记录接口，或令牌没有 `usage:read` 权限
`404`	`not_found`	你的账户下没有该 ID 的记录

错误使用统一的错误对象。