账户与目录 API

GET /v1/models、GET /v1/usage 与公开的 GET /api/v1/models/pricing：鉴权方式、示例响应、字段类型与单位，以及 HopBase 设置的响应头。

三个只读端点分别告诉你的代码：这把密钥能调哪些模型、还能花多少、各模型的牌价是多少。三者都不计费，也都不要求余额为正。

端点	鉴权	返回内容
`GET /v1/models`	密钥：`Authorization: Bearer sk-…` 或 `x-api-key: sk-…`	这把密钥所在分组提供的模型
`GET /v1/usage`	密钥：只认 `Authorization: Bearer sk-…`	这把密钥还能花多少，以及它的额度
`GET /api/v1/models/pricing`	无需鉴权	带牌价的公开模型目录

列出模型

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-opus-5-5",
      "object": "model",
      "type": "model",
      "display_name": "Claude Opus 5.5",
      "created_at": "2026-09-22T00:00:00Z"
    }
  ],
  "has_more": false,
  "first_id": "claude-opus-5-5",
  "last_id": "claude-haiku-4-5-20251001"
}

字段	类型	含义
`data[].id`	string	请求里要传的模型 ID，也是唯一应该依赖的字段
`data[].capabilities`	string[]	例如 `chat`、`reasoning`、`image_generation`
`data[].image_only`	boolean	图片模型为 `true`，其他模型不返回
`data[].context_window`、`context_length`、`max_input_tokens`	integer，Token	同一个值的三种写法，照顾不同客户端；未公布时不返回
`data[].max_output_tokens`	integer，Token	未公布时不返回
`data[].created`	integer，Unix 秒	本次响应的时间，不是发布日期
`data[].display_name`、`created_at`	string	仅 Claude 分组；`created_at` 是模型发布日期（RFC 3339）

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

余额与额度

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

{
  "is_active": true,
  "balance": 125.4,
  "remaining": 125.4,
  "unit": "USD",
  "quota": {
    "remaining": 125.4,
    "api_key_remaining": 125.4,
    "total": 0,
    "used": 3.12,
    "unlimited": true
  }
}

字段	类型	含义
`balance`	number	这把密钥此刻还能花的额度。密钥没设额度：即账户余额。密钥设了额度：即密钥剩余额度。团队成员与部门的密钥还会再按成员、部门本期剩余额度封顶
`remaining`	number	与 `balance` 相同
`is_active`	boolean	`balance` 大于 0 时为 `true`
`unit`	string	恒为 `"USD"`，并不代表币种，见下方说明
`quota.remaining`	number	与 `balance` 相同
`quota.api_key_remaining`	number	这把密钥的剩余额度；密钥没设额度时等于账户余额
`quota.total`	number	密钥额度；`0` 表示密钥没设额度
`quota.used`	number	这把密钥累计已扣费金额
`quota.unlimited`	boolean	密钥没设额度时为 `true`

金额单位是你的余额币种

所有金额都以账户余额的记账币种计——与控制台余额和「使用记录」里显示的数字一致。不要根据 unit 判断币种。

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

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

情况	状态码	响应体
没传密钥，或不是 `sk-` 开头的密钥	401	`{"is_active": false, "balance": 0, "message": "missing or invalid api key"}`
密钥不存在或已停用	401	`"message": "invalid api key"`
密钥已过期	200	`"is_active": false`，`"message": "api key expired"`
团队成员已停用	200	`"is_active": false`，`"message": "member disabled"`

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

公开模型目录

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"
        }
      ]
    }
  ]
}

字段	类型	含义
`code`	integer	成功为 `0`
`data[].platform`	string	模型接入所属的协议族（例如 `openai`、`claude`、`gemini`、`kling`），不是模型厂商——厂商看 `vendor`
`models[].id`	string	要传的模型 ID
`models[].name`	string	显示名称
`models[].vendor`	string	模型厂商，例如 `openai`、`google`；可能不返回
`models[].series`	string	控制台里把多个版本归为一组所用的系列；可能不返回
`models[].category`	string	`chat`、`image`、`video`、`audio` 或 `embedding`
`models[].capabilities`	string[]	例如 `chat`、`reasoning`、`image_generation`、`image_edit`、`video_generation`、`tts`
`models[].context_window`	integer，Token	未公布时不返回
`models[].price_unit`	string	本条目所有价格的计量单位：`token` = 每百万 Token，`second` = 每秒视频，`image` = 每张图，`character` = 每百万计费字符
`models[].input`、`cached_input`、`output`	number，美元 / `price_unit`	不适用缓存时不返回 `cached_input`；语音模型只用 `input`
`models[].long_context`	object	有长上下文档位时返回：输入 Token 超过 `threshold` 时，整笔请求按 `input_multiplier` / `cached_multiplier` / `output_multiplier` 计费
`models[].image`	object	按分辨率档位的每张价格，例如 `{"1k": …, "2k": …, "4k": …}`
`models[].video_tokens`	object	按档位（分辨率、有无声音、有无参考素材）的视频价格。单位跟随 `price_unit`：`token` 为每百万视频 Token，`second` 为每秒。键名是历史沿用

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

响应头

响应头	何时返回	含义
`x-request-id`	每个响应	本次请求的 ID，反馈问题时请附上
`Retry-After`	并发上限触发的 429；已知等待时间的 429 与 503	重试前需等待的秒数
`Retry-After-Ms`	并发上限触发的 429，以及其他已知等待时间的 429	同一等待时间，单位毫秒

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

列出模型

余额与额度

公开模型目录

响应头

本页目录