> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # 个人访问令牌 > 创建可自选权限和有效期的个人访问令牌，用它管理 API 密钥、读取余额和付款记录，并按条读取以美元计的用量记录，完成对账。 # 个人访问令牌 个人访问令牌是用于自动化管理 BeatAPI 账户的凭据。每个令牌带哪些权限由你决定，脚本只能做你允许的事：读取余额、管理 API 密钥、查看付款记录，或读取每个任务、每次文本请求花了多少钱等账户数据。调用模型、提交任务和工作流仍然使用 API 密钥。 ## 个人访问令牌与 API 密钥的区别 | | 个人访问令牌 | API 密钥 | | --- | ------------------------------------------------------------ | ----------------------------- | | 前缀 | `nap_` | `sk-` | | 用途 | 账户自动化，例如 `GET /v1/account` 和 `GET /v1/account/usage/records` | 模型、任务和工作流请求 | | 数量 | 每个账户最多 20 个，各有自己的名称 | 按需创建多个 | | 限制 | 由你选择的权限；没有独立的模型、IP 或消费额度限制 | 每个密钥可单独设置模型、IP 和消费额度限制 | | 有效期 | 可选：7、30、90、365 天，或永不过期 | 每个密钥可单独设置有效期 | | 可调用 | `/v1/account` 下的接口和 `GET /v1/usage` | 模型、任务和工作流接口以及 `GET /v1/usage` | ## 创建和管理令牌 1. 登录[控制台](https://beatapi.io/dashboard/security)，打开**账户安全**。 2. 点击**创建个人令牌**，输入名称，勾选令牌需要的权限，并选择有效期：7、30（默认）、90、365 天，或永不过期。 3. 完成安全验证后复制令牌。完整令牌仅展示这一次，关闭窗口后会从页面中清除。 4. 把它作为密钥保存在运行自动化程序的环境中，例如 `BEATAPI_PERSONAL_TOKEN`。 每个账户最多可有 20 个令牌。请给每个令牌起一个能说明用途的名称，并且只授予它需要的权限。令牌列表会显示每个令牌的名称、权限、有效期和最近使用时间。 重命名令牌随时可以进行，不需要安全验证。修改令牌权限和撤销令牌都需要安全验证。修改后的权限直接作用于同一个令牌，无需重新部署。**撤销**会删除令牌，使用它的工具立即失去访问权限。请只在可信服务器上保存令牌，不要放进浏览器代码、移动应用或共享代码仓库。 在支持多个令牌之前创建的令牌继续有效，权限保持不变。 ## 权限 令牌只带有你勾选的权限。调用需要令牌所没有的权限时，会返回 `403 forbidden`，错误信息会指明缺少哪项权限。 | 权限 | 允许的操作 | 接口 | | ---------------- | ------------------------------- | ------------------------------------------------------------------------------------ | | `usage:read` | 读取用量记录和用量汇总 | `GET /v1/account/usage/records`、`GET /v1/account/usage/records/{id}`、`GET /v1/usage` | | `api_key:read` | 列出和读取 API 密钥，密钥内容已脱敏 | `GET /v1/account/keys`、`GET /v1/account/keys/{id}` | | `api_key:write` | 创建 API 密钥（完整密钥只返回一次），以及编辑、停用和删除 | `POST /v1/account/keys`、`PATCH /v1/account/keys/{id}`、`DELETE /v1/account/keys/{id}` | | `api_key:reveal` | 读取已有 API 密钥的完整内容 | `POST /v1/account/keys/{id}/reveal` | | `wallet:read` | 读取付款（充值）记录 | `GET /v1/account/payments` | | `profile:read` | 读取账户资料、余额和通知设置 | `GET /v1/account`、`GET /v1/account/notifications` | | `profile:write` | 修改通知设置 | `PATCH /v1/account/notifications` | 令牌不能充值、修改登录或安全设置，也不能管理其他令牌，这些操作只能在控制台完成。只有确实需要读取密钥内容的令牌才应授予 `api_key:reveal`。 ## 可调用的接口 请求时发送 `Authorization: Bearer `。每个接口都需要表中所列的权限。 | 接口 | 权限 | 用途 | | ------------------------------------ | ---------------- | ----------------------------- | | `GET /v1/account` | `profile:read` | 账户资料和以美元计的余额 | | `GET /v1/account/notifications` | `profile:read` | 读取余额通知设置 | | `PATCH /v1/account/notifications` | `profile:write` | 修改通知方式、阈值或邮箱 | | `GET /v1/account/payments` | `wallet:read` | 按时间倒序列出付款记录 | | `GET /v1/account/keys` | `api_key:read` | 按时间倒序列出 API 密钥 | | `GET /v1/account/keys/{id}` | `api_key:read` | 读取一个 API 密钥 | | `POST /v1/account/keys` | `api_key:write` | 创建 API 密钥 | | `PATCH /v1/account/keys/{id}` | `api_key:write` | 编辑、停用或重新启用 API 密钥 | | `DELETE /v1/account/keys/{id}` | `api_key:write` | 删除 API 密钥 | | `POST /v1/account/keys/{id}/reveal` | `api_key:reveal` | 读取 API 密钥的完整内容 | | `GET /v1/account/usage/records` | `usage:read` | 按时间倒序列出账户的计费请求 | | `GET /v1/account/usage/records/{id}` | `usage:read` | 按任务 ID 或请求 ID 读取一条记录 | | `GET /v1/usage` | `usage:read` | 账户汇总与明细，见[快速指南](/quick-guide) | `/v1/account` 下的接口用 API 密钥调用会返回 `403 forbidden`；`GET /v1/usage` 既接受 API 密钥，也接受带 `usage:read` 权限的令牌，返回同一份汇总。响应内容包在 `data` 中。ID 是字符串，时间是 Unix 秒，金额以美元计。列表返回 `object`、`data`、`has_more` 和 `next_cursor`，并支持 `limit`（1–100，默认 20）和 `cursor`。未知的查询参数会返回 `400 bad_request`。 ## 读取余额 需要 `profile:read` 权限。 ```bash curl https://api.beatapi.io/v1/account \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" ``` ```json { "data": { "object": "account", "id": "1042", "username": "ada", "display_name": "Ada", "email": "ada@example.com", "credit_balance": 42.5, "currency": "USD" } } ``` ## 列出 API 密钥 需要 `api_key:read` 权限。密钥内容已脱敏，只返回开头几位字符 `key_prefix`。要读取单个密钥，请用 `GET /v1/account/keys/{id}`。 ```bash curl -G https://api.beatapi.io/v1/account/keys \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ --data-urlencode "limit=20" ``` ```json { "data": { "object": "list", "data": [ { "object": "api_key", "id": "1287", "title": "production", "key_prefix": "sk-Ab3d", "status": "active", "created_at": 1793200000, "last_used_at": 1793247312, "expires_at": null, "remaining_credits": null, "credits_used": 18.42, "models": [], "allowed_ips": [] } ], "has_more": false } } ``` ## 创建 API 密钥 需要 `api_key:write` 权限。只有 `title` 必填。`expires_at`（Unix 秒）、`remaining_credits`（美元）、`models` 和 `allowed_ips` 均可选；省略表示不过期、无消费额度限制、可用所有模型、不限 IP。完整密钥只会出现在这次响应的 `key` 字段中，之后读取只返回 `key_prefix`，请立即保存。 ```bash curl -X POST https://api.beatapi.io/v1/account/keys \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "ci-runner", "remaining_credits": 20, "models": ["deepseek-v4.1-flash"], "allowed_ips": ["203.0.113.7"]}' ``` ```json { "data": { "object": "api_key", "id": "1304", "title": "ci-runner", "key_prefix": "sk-Qm8R", "key": "sk-Qm8RExampleFullKeyShownOnlyInThisResponse", "status": "active", "created_at": 1793250000, "last_used_at": null, "expires_at": null, "remaining_credits": 20, "credits_used": 0, "models": ["deepseek-v4.1-flash"], "allowed_ips": ["203.0.113.7"] } } ``` 用 `PATCH /v1/account/keys/{id}` 编辑密钥，可传 `title`、`status`（`active` 或 `disabled`）、`expires_at`（`null` 表示永不过期）、`remaining_credits`（`null` 表示不限额）、`models`（`[]` 表示所有模型）和 `allowed_ips`。`DELETE /v1/account/keys/{id}` 返回 `object`、`id` 和 `deleted: true`。 ## 读取 API 密钥的完整内容 需要 `api_key:reveal` 权限。它与 `api_key:read` 相互独立：能列出密钥的令牌，除非另外授予此权限，否则无法读取密钥内容。 ```bash curl -X POST https://api.beatapi.io/v1/account/keys/1287/reveal \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" ``` ```json { "data": { "object": "api_key_secret", "id": "1287", "key": "sk-Ab3dExampleFullKey" } } ``` ## 列出付款记录 需要 `wallet:read` 权限。`status` 可选 `paid`（默认）、`pending`、`failed`、`expired`、`reviewing` 或 `all`。`currency` 是支付币种，`USD` 或 `CNY`；`credits` 是这笔付款增加的余额，以美元计。 ```bash curl -G https://api.beatapi.io/v1/account/payments \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ --data-urlencode "status=paid" \ --data-urlencode "limit=20" ``` ```json { "data": { "object": "list", "data": [ { "object": "payment", "id": "5531", "order_no": "ORD20261027153012", "status": "paid", "amount_paid": 20, "currency": "USD", "credits": 20, "payment_method": "stripe", "created_at": 1793100000, "paid_at": 1793100042 } ], "has_more": false } } ``` ## 修改通知阈值 需要 `profile:write` 权限；用 `GET /v1/account/notifications` 读取设置需要 `profile:read`。可传 `type`（`email` 或 `none`）、`threshold_credits` 和 `notification_email` 中的任意几个。用量使余额低于阈值时，BeatAPI 会通知你；`0` 表示使用默认值。响应是更新后的设置，其中 `effective_threshold_credits` 是实际生效的阈值。 ```bash curl -X PATCH https://api.beatapi.io/v1/account/notifications \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{"threshold_credits": 5}' ``` ```json { "data": { "object": "notification_settings", "type": "email", "threshold_credits": 5, "effective_threshold_credits": 5, "default_threshold_credits": 1, "notification_email": "billing@example.com", "account_email": "ada@example.com" } } ``` ## 核对单个任务 保存创建任务时返回的 `data.id`，然后查询： ```bash curl https://api.beatapi.io/v1/account/usage/records/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" ``` ```json { "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-`，也可以直接用这个值查询。用任务创建请求的请求 ID 查询，返回的是与任务 ID 相同的记录。 ## 列出用量记录 ```bash 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" ``` ```json { "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 密钥调用了账户接口 | | `404` | `not_found` | 你的账户下没有该 ID 的记录、付款或 API 密钥 | 错误使用统一的[错误对象](/errors)。