# 额度与计费 (https://hypit.ai/zh/api-reference/billing/)

> 一次调用怎么定价，任务预扣多少，钱什么时候回来。

一个账号只有一份余额，并且以\*\*额度（credits）\*\*计量。没有单独的美元钱包，没有按厂商分账的子余额，
也没有按模态预付的池子。图片、视频的每一秒、每千 token、每一秒音频，都从同一个数字里扣。

当前价格见[定价页](/zh/commercial/pricing)，以及每个模型的
[模型卡片](/zh/api-reference/models)上的 `pricing.credits`。这一页讲的是不会变的机制。

## 一次调用怎么定价 [#一次调用怎么定价]

1. 模型费率表给出一个**基础费率**，单位是它按什么计费：每张图、每次请求、每秒视频、每千 token、
   每千字符、每秒音频。
2. 比率表在此之上做乘法：`size_ratio`、`quality_ratio`、`resolution_ratio` 和 `flag_ratio` 都是纯
   乘数，所以同一模型下 1080p 和 480p 的一秒是同一个费率乘上不同的系数。长上下文模型还会有一条
   按 `min_prompt_tokens` 分档的 `token_tiers` 阶梯。
3. 结果就是这个模型的**对外价格**，再由一个固定的平台常数投影到额度刻度上，中间乘以一个按模型
   设置的乘数——那是我们做促销和溢价用的。
4. 额度量化到小数点后四位，与账本结算用的是同一个精度网格。

第 3 步就是为什么接口在 USD 数字旁边还要单独发布 `pricing.credits`，也是为什么客户端必须读它而不
是自己算：那个按模型的乘数刻意不公开，所以任何基于美元数字的换算都会算错，而且恰好错在算错要
花钱的那些模型上。

路由不会改变你的价格。同一个模型我们可能根据产能和健康度从几家上游中任选一家来服务，它们对我们
的收费各不相同——但客户价格由模型决定，与最终是谁接的单无关。

## 同步调用 [#同步调用]

`/v1/chat/completions`、`/v1/audio/speech` 和 `/v1/audio/transcriptions` 在上游返回之后，按它报告
的用量定价，并与请求日志一起在同一个本地事务里扣费。要么整体提交，要么什么都不发生。

调用发出之前会先做一次余额检查，付不起的请求直接拒绝。这个检查不会「失败即放行」：如果账本读不到，
请求以 `503 precheck_failed` 被拒绝，而不是不计量地放过去。

## 异步任务 [#异步任务]

因为任务的真实成本要到结束才知道，提交时会按估算**预扣**额度：

```text
提交    ─►  预扣 est_credits            （余额立刻下降）
终态    ─►  succeeded     → 按真实用量结算
            failed        → 已扣的全额退回
            queue_expired → 已扣的全额退回
```

* **低于估算**：差额退回。
* **高于估算**：差额补扣。最终结算允许把余额压成轻微负数——已经发生的成本必须被记录——这会体现为
  一条 `overdraft`（透支）条目，由下一次发放的额度吸收。
* **失败或排队超时**：已经实际扣掉的全额退回；任务的费用列归零，而估算值留在行上，作为「扣了多少
  又冲回多少」的审计痕迹。

最后一条也覆盖了那个尴尬的情况：上游确实生成了东西，但我们拿不到可下载的产物时，任务判为失败并
退款。你永远不会为一个取不到的结果付钱。

退款回到**当初扣款时用的那几笔额度上**，而不是新发一笔。所以退回的订阅额度仍带原来的周期到期时间，
退回的加购包额度仍然不过期。

任务上的三次资金动作——预扣、补扣、退款——各自由幂等键保护，所以重复的轮询或重复到达的上游回调都
不会造成二次扣款或二次退款。

## 额度从哪来，按什么顺序花 [#额度从哪来按什么顺序花]

两个来源：

* **订阅**发放，每个计费周期刷新，随周期过期；
* **加购包**，一次性购买，不过期。

扣费**先扣订阅额度，再扣加购包**。这个顺序是刻意的：先花那些不花就作废的，后花能留住的。

## 入口处不允许透支 [#入口处不允许透支]

不存在「先用后结」。余额一旦覆盖不了下一次调用，这次调用就不会发生：

```json
{
  "error": {
    "message": "this call costs about 41.6 credits and you have 3.2; top up or upgrade your plan to continue",
    "type": "insufficient_quota",
    "code": "insufficient_credits",
    "param": null
  }
}
```

HTTP `402`。异步提交时同样的检查发生在任务创建之前，所以这里的 `402` 意味着什么都没预扣、什么都
没入队。

<Callout type="info" title="估算是刻意偏保守的">
  任务的预扣按请求**可能**产生的成本报价，包括请求字段表达不了的维度——比如某个模型默认生成一条音轨
  并因此把每秒费率翻倍。事前拒绝一个保守估算是可以补救的；为一段客户付不起的视频收到上游账单则不能。
</Callout>

## 怎么看余额 [#怎么看余额]

余额、账本和用量是**账户**接口，不是 API 接口。它们挂在 `/api/hub/billing/*` 下，需要一个已登录的
浏览器会话——`sk-hh-` Key 刻意不足以在 `/v1` 之外读取或动用账号的钱。

在 [hypit.ai](https://hypit.ai) 的账户面板里可以看到：

* **额度**——当前余额，按订阅、加购包和透支拆分，以及套餐和续费时间；
* **账单记录**——账本，每条发放、扣费、调整、退款和过期各一行；
* **用量**——按天、按模型、按模态汇总的额度消耗与请求数。

用量的时间窗按 UTC+8 计算，这是本产品各处统一使用的计费日。

<Callout type="warn" title="`/v1` 响应上没有任何费用相关的响应头">
  如果你习惯了 `x-ratelimit-remaining-*` 或者按次的费用响应头，这里没有。单次调用的消耗可以在响应体
  的 `usage` 里看到（前提是上游报了），权威数据在账户面板的用量视图里。我们只加两个头：
  `X-Request-Id`，以及拒绝时的 `Retry-After`。
</Callout>

## 免费模型 [#免费模型]

模型卡片的 pricing 里可能带 `"free": true`，此时美元数字和额度数字都是零。免费模型仍然要求余额
非空——闸门问的是「还剩点什么没有」——并且同样占用你的限流和并发额度。