计费与余额

提供以下计费接口：/billing/balance 余额检查、/billing/usage 时间维度下的用量情况、/billing/records 逐条明细。 调用时请使用对应的 API Key 作为查询目标，返回金额均以人民币计价。

共同约定

• 认证——Authorization: Bearer sk-gw-…， 与调用模型接口使用同一把 Key；控制台会话 Cookie 亦可。
• 范围——返回该 Key 所属账号的全部用量， 非单把 Key 的用量。同一账号下多把 Key 的消费合并统计； 如需按 Key 拆分，请通过明细接口按时间与模型自行归集。
• 金额——一律为人民币字符串，形如 "4.659506"。采用字符串而非数字类型：JSON 数字在多数语言中解析为双精度浮点，逐条累加的结果与服务端合计存在偏差。 金额字段旁始终附带 "currency": "CNY"。
• 精度——最多 6 位小数（0.000001 元）。 单次对话调用的费用常低于 1 分，保留 2 位将全部归零。
• 时间——统一为 RFC3339 UTC，形如 2026-08-01T00:00:00Z。时间窗为左闭右开 [start, end)，同一条记录仅归属一个窗口， 连续区间求和即为总额，边界不重复计入。

查余额

curl https://heiyutv.com/api/v1/billing/balance \
  -H "Authorization: Bearer sk-gw-XXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "currency": "CNY",
  "balance": "88.14",
  "as_of": "2026-08-22T09:30:00Z"
}

balance 为当前可用余额。建议对该值设置阈值告警。

余额为零或负数时，对话类接口在转发之前即被拦截并返回 402 ERR_INSUFFICIENT_FUNDS，被拦截的请求不计费。

视频接口不做余额预检，余额不足时任务仍会被受理并正常 生成，费用于结算时扣除，余额可能因此为负。原因是视频为异步任务， 创建时无法预知实际消耗的 token 数量，按预估值拦截会拒绝掉本可正常完成 的请求。请通过本接口自行监控余额。

查用量汇总

返回指定区间内的消费总额与 token 消耗量， 并附同一区间按模型拆分的结果。两者在同一响应中返回， 以避免分两次请求时因时间边界不一致导致数据无法对齐。

curl "https://heiyutv.com/api/v1/billing/usage?start=2026-08-01T00:00:00Z&end=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer sk-gw-XXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "currency": "CNY",
  "start": "2026-08-01T00:00:00Z",
  "end":   "2026-09-01T00:00:00Z",
  "total": {
    "requests": 1284,
    "prompt_tokens": 913402,
    "completion_tokens": 355104,
    "total_tokens": 1268506,
    "amount": "61.8342"
  },
  "by_model": [
    {
      "model": "seedance-2.0-custom",
      "requests": 7,
      "prompt_tokens": 0,
      "completion_tokens": 354466,
      "total_tokens": 354466,
      "amount": "59.3128"
    },
    {
      "model": "deepseek-v4-flash",
      "requests": 1277,
      "prompt_tokens": 913402,
      "completion_tokens": 638,
      "total_tokens": 914040,
      "amount": "2.5214"
    }
  ]
}

单次查询跨度上限为 366 天，超出返回 400 ERR_BAD_RANGE。更长区间请分段查询。

拉逐条明细

每一次计费调用对应一条记录，按时间倒序返回。 适用于账务对账、内部成本分摊，以及将消费数据同步至自有账务系统。

curl "https://heiyutv.com/api/v1/billing/records?start=2026-08-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer sk-gw-XXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "currency": "CNY",
  "data": [
    {
      "id": "vt_666bffed506011cdd280f7c3",
      "ts": "2026-08-22T08:59:09Z",
      "model": "seedance-2.0-custom",
      "prompt_tokens": 0,
      "completion_tokens": 50638,
      "total_tokens": 50638,
      "amount": "4.659506",
      "status": "success"
    },
    {
      "id": "req_01M0M748T1RMV6JJDMXASCZK83",
      "ts": "2026-08-22T07:49:23Z",
      "model": "deepseek-v4-flash",
      "prompt_tokens": 812,
      "completion_tokens": 96,
      "total_tokens": 908,
      "amount": "0.001974",
      "status": "success"
    }
  ],
  "next_cursor": "req_01M0M748T1RMV6JJDMXASCZK83"
}

翻页请使用 cursor，不要使用 offset。该数据表持续写入，按偏移量翻页会导致记录遗漏与重复。 响应中不含 next_cursor 即表示已到末页。

cursor = None
while True:
    r = requests.get(url, params={"start": start, "limit": 200, "cursor": cursor},
                     headers={"Authorization": f"Bearer {key}"}).json()
    for row in r["data"]:
        ...
    cursor = r.get("next_cursor")
    if cursor is None:
        break

字段说明

费用构成

按 token 计费，无月费、无最低消费、无并发费用。各模型单价见定价页； 账号如有专属折扣，控制台定价页显示折后价。

视频模型不按次计价，按输出 token 计费，单价分四档， 由输入是否含视频 × 输出分辨率决定， 详见视频生成。

失败不计费。请求被拒绝、上游报错、 流式返回 0 个输出 token，均不产生费用。 明细接口中仍返回对应记录，amount 为 "0.00"。

余额来源

在充值页下单支付后余额自动到账， 最低 ¥50，各套餐默认赠送面值 5% 的额度。 赠送额度在消费时优先扣除，用尽后方扣除充值部分； 仅充值部分支持退款与开票。

退款与发票的规则及申请入口位于控制台「账户」，完整条款见《充值后具体计费规则》。

常见对账问题

错误

完整错误码见错误码。