账户与目录 API

三个端点都不计费，也都不要求余额为正。

列出模型

GET /v1/models 接受 Authorization: Bearer sk-… 或 x-api-key: sk-…；GET /v1/usage 只认 Authorization: Bearer sk-…。

curl https://api.hop-base.com/v1/models \
  -H "Authorization: Bearer sk-your-key"

列表只包含密钥所含分组的模型（包含多个分组时为全部分组的并集），一次返回完整列表（不分页）。OpenAI 兼容分组的密钥拿到 OpenAI 格式的列表：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-6-astra",
      "object": "model",
      "created": 1790222400,
      "owned_by": "hopbase",
      "capabilities": ["chat", "reasoning"],
      "context_window": 1050000,
      "context_length": 1050000,
      "max_input_tokens": 1050000,
      "max_output_tokens": 128000
    }
  ]
}

Claude 分组的密钥拿到 Anthropic 格式：

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-5-5",
      "object": "model",
      "type": "model",
      "display_name": "Claude Sonnet 5.5",
      "created_at": "2026-09-28T00:00:00Z"
    }
  ],
  "has_more": false,
  "first_id": "claude-sonnet-5-5",
  "last_id": "claude-haiku-4-5-20251001"
}

has_more、first_id、last_id 只为兼容 SDK 保留：列表从不分页，不要拿它们翻页。除 id 外，部分模型可能缺少其他字段；遇到不认识的字段按可选处理。

余额与计价币种：USD

自 2026-10-01 起，账户余额、密钥额度、扣费与使用记录一律以美元（USD）计价：模型按官方美元价乘以分组倍率扣费，控制台与 GET /v1/usage 显示的都是美元金额。

• 已有余额：切换时已按固定比例换算为美元，可用量不变；分组价格与密钥都不变。
• 单次扣费：为兼容已接入的程序，响应里的 cost 与 X-HopBase-Cost 仍是同一笔扣费的人民币金额（最多 6 位小数），currency 恒为 CNY；实际从余额扣除的美元金额读 cost_usd 与 X-HopBase-Cost-USD，与「使用记录」一致。见扣费。
• 充值：付款币种、手续费与到账金额以「充值」页付款前显示的为准，手续费单独列出、不计入到账金额；人民币对公转账或线下充值的到账美元金额以客服确认为准。

余额与额度

curl https://api.hop-base.com/v1/usage \
  -H "Authorization: Bearer sk-your-key"

下例是一把额度为 $10、已用 $2 的密钥：

{
  "is_active": true,
  "balance": 8,
  "remaining": 8,
  "unit": "USD",
  "ledger_currency": "USD",
  "balance_cny": 54.4,
  "balance_usd": 8,
  "quota": {
    "remaining": 8,
    "api_key_remaining": 8,
    "total": 10,
    "used": 2,
    "unlimited": false,
    "remaining_cny": 54.4,
    "remaining_usd": 8,
    "api_key_remaining_cny": 54.4,
    "api_key_remaining_usd": 8,
    "total_cny": 68,
    "total_usd": 10,
    "used_cny": 13.6,
    "used_usd": 2
  }
}

balance 的取值规则：

• 密钥没设额度：即账户余额。
• 密钥设了额度：即密钥剩余额度。
• 团队成员与部门的密钥还会再按成员、部门本期剩余额度封顶。

不带后缀的金额指 balance、remaining、quota.remaining、quota.api_key_remaining、quota.total、quota.used。

每个金额都另有人民币与美元两个带后缀的字段：

设了额度的密钥仍然从账户余额里扣费：账户余额先用完时，即使这里的 balance 显示还有额度，请求也会返回 402。

这个端点不使用标准错误结构，出错时返回如下：

第一种 401 的完整响应体：

{"is_active": false, "balance": 0, "message": "missing or invalid api key"}

这两种 200 响应同样带 ledger_currency 和 balance_cny / balance_usd（均为 0）。

请以 is_active 判断，不要只看 HTTP 状态码。逐笔扣费明细请在控制台「使用记录」查看。

单次请求、单个任务与单条记录的扣费

同步请求与异步任务的每笔扣费都给出两种币种：cost_usd 是实际从余额扣除的美元金额，与控制台「使用记录」里这一条相同；cost 是同一笔扣费的人民币金额，为兼容已接入的程序恒为人民币，因此 currency 恒为 CNY。cost_usd 最多 8 位小数，cost 取 6 位。

同步请求（对话、生图、语音）

计费的同步请求在三个响应头里返回本次实际扣费：

非流式的 JSON 响应还会在根对象的 usage 里带同样的 cost、cost_usd 与 currency：

{
  "id": "chatcmpl-abc",
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "ok" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 1, "total_tokens": 10, "cost": 0.001197, "cost_usd": 0.000176, "currency": "CNY" }
}

• 响应原本没有 usage 时会新增一个，例如语音合成 POST /v1/t2a_v2 的 JSON 响应。usage 里原有的字段（如 xAI 的 cost_in_usd_ticks）保持不变。
• usage 已经带有 cost、cost_usd 或 currency、或者不是对象时，响应体保持原样，请读响应头。
• 二进制响应（如语音合成返回的音频）只有响应头。
• 流式（SSE）响应都不带：响应头在生成开始前已经发出，最后的用量事件原样下发。流式请求的扣费请在控制台「使用记录」查看。
• 生图耗时超过约 40 秒时，服务端会先发出 200 响应头再写保活空白，此时响应头里没有扣费，请读响应体的 usage.cost / usage.cost_usd。
• 没有扣费的响应（如模型列表、未计费的错误）都不带。失败的请求仍产生扣费时，错误响应带响应头，错误体保持原样。
• HopBase 自动重试时只对最终完成的那一次计费，返回的就是这一次的金额。多分组密钥按实际服务的分组计价。
• 设置了销售倍率的密钥，返回的是从你余额实际扣除的金额，不含加价。
• 客户端在响应到达前断开时，本次仍按实际用量计费，可在「使用记录」查看。

异步任务查询（图片与视频）

任务结束后，根对象的 usage 带 cost_usd（本任务实际从余额扣除的美元金额）、cost（同一笔扣费的人民币金额）与 currency（cost 的币种，恒为 CNY）。0 表示失败且未扣费；单查任务时只有创建任务的密钥能看到这些字段。

{
  "id": "vt-1",
  "status": "completed",
  "usage": { "cost": 3.4, "cost_usd": 0.5, "currency": "CNY" }
}

任务列表（如不带任务 ID 的 GET /v1/video/tasks）里，每个终态任务的 usage 也带同样的 cost、cost_usd 与 currency。列表按账户列出，同一账户其他密钥创建的任务同样带金额。

控制台使用记录

「使用记录」页面读取 GET /api/v1/user/usage 与 GET /api/v1/user/usage/stats（控制台登录鉴权，不接受 sk- 密钥）。

每条记录带 ledger_currency（2026-10-01 起为 USD）、cost_cny、cost_usd，即这条记录扣费的人民币与美元金额；页面按美元显示。

统计结果带 ledger_currency、total_charged_cny、total_charged_usd，by_model、by_key、by_group、by_department、by_member 的每一项带 cost_cny / cost_usd。

统计里原有的 total_cost 是乘分组倍率之前的官方美元原价，不是你的扣费；扣费请看 total_charged_*。

公开模型目录

curl https://api.hop-base.com/api/v1/models/pricing

无需密钥。响应允许任意站点跨域读取，最多缓存 5 分钟（Cache-Control: public, max-age=300）。价格是未乘分组倍率的美元牌价；各模型你实际支付的价格见登录后的模型广场。

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "platform": "openai",
      "models": [
        {
          "id": "gpt-6-astra",
          "name": "GPT-6 Astra",
          "context_window": 1050000,
          "capabilities": ["chat", "reasoning"],
          "vendor": "openai",
          "category": "chat",
          "input": 10,
          "cached_input": 1,
          "output": 50,
          "long_context": {
            "threshold": 272000,
            "input_multiplier": 2,
            "cached_multiplier": 2,
            "output_multiplier": 1.5
          },
          "price_unit": "token"
        }
      ]
    },
    {
      "platform": "minimax",
      "models": [
        {
          "id": "speech-2.8-hd",
          "name": "MiniMax Speech 2.8 HD",
          "capabilities": ["tts"],
          "vendor": "minimax",
          "series": "minimax-speech",
          "category": "audio",
          "input": 100,
          "output": 0,
          "price_unit": "character"
        }
      ]
    }
  ]
}

platform 例如 openai、claude、gemini、kling；模型厂商看 vendor。

输入 Token 超过 threshold 时，整笔请求按 input_multiplier / cached_multiplier / output_multiplier 计费。

video_tokens 按分辨率、有无声音、有无参考素材分档。price_unit 为 token 时是每百万视频 Token，为 second 时是每秒。键名是历史沿用。

同一模型通过多个分组提供时，可能出现在多个 platform 下。今后可能新增字段，不认识的字段请忽略。

响应头

HopBase 不会在响应头里返回你的并发上限、在途请求数或剩余余额。余额请用 GET /v1/usage 查询，上限见并发、超时与计费。部分模型响应会带有自身的限流头（x-ratelimit-*、anthropic-ratelimit-*），它们描述的不是你账户或密钥的上限，不要据此限流。

下一步

• 并发、超时与计费：并发上限、超时与计费规则
• 错误码与重试：各错误码的含义以及是否该重试
• 可用模型：查看密钥可用的模型 ID