余额与 API 密钥限额

每个生成内容的请求都从你的预付 USD 余额中支付。你还可以限制每个 API 密钥可以花费的金额。本页介绍如何读取余额和密钥的上限，以及请求因其中任何一项被拒绝时该怎么办。

这两个端点都需要通过 Authorization: Bearer 发送 API 密钥。详见认证。

GET /v1/balance 返回你账户的余额。

curl "https://api.sakuranbo.ai/v1/balance" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY"

const response = await fetch("https://api.sakuranbo.ai/v1/balance", {
  headers: {
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.get(
    "https://api.sakuranbo.ai/v1/balance",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
)
print(response.json())

响应包含以下字段：

• available_micro_usd 和 available_usd 是新请求可以使用的金额。
• held_micro_usd 和 held_usd 是运行中的请求已预留的金额。

每个金额都给出两次：一次是以 micro USD（1 USD = 1,000,000 micro USD）为单位的整数，另一次是以 USD 表示的十进制字符串。

如需充值，请打开控制台的充值页面。详见定价与计费。

Sakuranbo AI 接受一个会产生费用的请求时，会预留一笔金额。预留的金额从 available 转入 held。请求结束时，会按实际费用扣费，差额回到 available。被取消或被拒绝的请求，或在模型生成任何输出之前就失败的请求，会收回全部预留，你不会被扣费。如果对话流在模型开始生成输出（包括推理输出）之后中断，该请求会计费，包括已经生成的输出，其余的预留回到 available。详见对话。

在极少数情况下，图像或视频任务会在 Sakuranbo AI 确认模型提供方是否已收到请求之前失败。此时任务会变为 failed，错误代码为 upstream_error。它的预留会一直留在 held 中，直到 Sakuranbo AI 确认该请求是否计费，不会自行回到 available。如果它一直留在 held 中，请联系支持团队并提供任务 ID。

由于有预留，在请求运行期间，available 可能低于你的总余额。新请求会按 available 检查。

支出上限属于某一个 API 密钥。你在控制台的 API 密钥页面创建密钥时设置它。上限包含一个 USD 金额和一个周期。周期为 none, day, month 之一。

• day：密钥在一个 UTC 自然日内可以花费的金额。计数器在 UTC 00:00 重新开始计算。
• month：一个 UTC 自然月的金额。计数器在每月 1 日 UTC 00:00 重新开始计算。
• none：密钥整个存续期间的累计金额。计数器永不重新开始。

没有上限的密钥可以花费到余额允许的数额，但仍会统计用量。你还可以给密钥设置到期日。使用已过期密钥的请求会返回 401。详见认证。

你在控制台的 Playground 中运行的请求不使用 API 密钥，因此不会计入任何密钥的上限。

GET /v1/key 返回发送该请求的密钥，包括它的上限和用量。

curl "https://api.sakuranbo.ai/v1/key" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY"

const response = await fetch("https://api.sakuranbo.ai/v1/key", {
  headers: {
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.get(
    "https://api.sakuranbo.ai/v1/key",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
)
print(response.json())

响应包含以下字段：

• limit 在密钥没有上限时为 null。否则它包含金额和周期。
• usage.used_micro_usd 和 usage.used_usd 是运行中的请求已预留的金额，加上当前周期内已经扣除的金额。
• usage.remaining_micro_usd 和 usage.remaining_usd 是在上限内还可以使用的剩余金额。密钥没有上限时它们为 null。
• usage.resets_at 是计数器重新开始计算的时间。周期为 none 时为 null。

请求在两种情况下会被以 402 拒绝。error.details.limit_source 用来区分这两种情况。

balance_insufficient（limit_source 为 balance）：你的 available 余额低于该请求需要预留的金额。error.details 包含 requested_micro_usd、available_micro_usd 和 shortfall_micro_usd，以及以 USD 表示的同样三个金额 requested_usd、available_usd 和 shortfall_usd。请充值后重新发送请求。

key_limit_exceeded（limit_source 为 key）：密钥的用量加上该请求需要预留的金额，超过了密钥的上限。恰好达到上限的请求会被接受。error.details 包含 period、resets_at、requested_micro_usd、limit_micro_usd 和 used_micro_usd，以及以 USD 表示的同样三个金额。如果两种情况同时适用，会先检查密钥的上限。

请注意以下几点：

• 预留会立即计入，因此即使请求的实际费用在上限之内，它也可能被拒绝。更小的请求（例如 max_tokens 更低的对话请求）预留的金额更少。
• 被拒绝的请求不会扣费，也不会创建任务。
• 402 响应没有 Retry-After 响应头。对于密钥的上限，请读取 error.details.resets_at 来了解计数器何时重新开始计算。如果它为 null，说明上限针对密钥的整个存续期间，你需要改用上限更高的密钥。

可用余额低于你选定的额度时，你可以收到 balance.low Webhook 事件。请在控制台的设置中设置这个额度。详见 Webhook。

MCP 服务器提供工具 get_balance，读取的是同样的数据。详见 MCP 服务器。

GET /v1/key 返回相同的错误代码。完整的错误代码列表请参阅错误。