API 参考
HopBase API 的 Base URL、按分组的密钥鉴权、请求 ID、错误结构与并发限制,以及全部端点一览。
HopBase 是多模型 API 网关:对话、图片、视频、语音都通过同一个域名 https://api.hop-base.com 调用,协议沿用 OpenAI 与 Anthropic 的官方格式,现有 SDK 只需换 Base URL 和密钥。本节每个端点一页,参数表与示例都从 OpenAPI 描述生成。
端点一览
/v1/video/generate提交视频任务GET/v1/video/tasks/{task_id}查询视频任务GET/v1/video/tasks列出视频任务POST/v1/kling/subjects创建自定义主体GET/v1/kling/subjects查询自定义主体POST/v1/kling/faces对口型人脸识别Base URL
| 协议 | Base URL | 用于 |
|---|---|---|
| OpenAI 兼容 | https://api.hop-base.com/v1 | 对话、Responses、图片、视频、语音、/v1/models、/v1/usage |
| Anthropic | https://api.hop-base.com | Claude 模型的 /v1/messages(SDK 里不带 /v1) |
协议由客户端和模型类型共同决定,不由密钥格式决定。完整的场景对照(Claude Code、Codex CLI、各模型种类)见 Base URL 与协议。万相 / 快乐马使用原生视频路径 /api/v1/services/aigc/video-generation/video-synthesis,挂在域名根下。
鉴权
所有端点用控制台「API 密钥」里创建的 sk- 密钥鉴权,两种请求头任选其一:
Authorization: Bearer sk-你的密钥
x-api-key: sk-你的密钥Gemini 原生协议(/v1beta/models/{model}:generateContent)另接受 x-goog-api-key: sk-你的密钥 与 URL 参数 ?key=。GET /v1/usage 只认 Authorization: Bearer。
创建或编辑密钥时可以选一个或多个分组(例如「Codex Pro」「Claude Max 企业版」「GPT Image 全系」),可以跨平台。密钥只能调这些分组提供的模型,每个请求还要用该模型支持的端点:Claude 模型可用 /v1/messages 与 /v1/chat/completions,但不支持 /v1/responses,所以只含 Claude 分组的密钥调 /v1/responses 返回 404「当前平台不支持该 API 路径」;模型不在密钥的任何分组里时返回 404 model_not_found。同一个项目既要对话又要生图时,把两个分组加进同一把密钥即可(也可以编辑已有密钥追加分组)。模型有重叠的分组不能放进同一把密钥,订阅类分组只能单独成一把密钥。每次请求只由覆盖所请求模型的那个分组服务并按它计费,不会悄悄换到别的分组。唯一例外是「GPT 官方直连(Azure)」与 Codex Plus 或 Codex Pro 之一、或与「GPT Image 全系」混用:两组都有的型号优先走 Azure,Azure 在还没输出任何内容前失败时自动切到另一个分组,按实际服务的分组计费并在使用记录中显示(见分组怎么选)。可用模型以这把密钥调 GET /v1/models 的返回为准,即它所有分组模型的并集。
请通过环境变量或部署平台注入密钥,不要写进源码或提交到 Git。
请求 ID
每个响应都带响应头 x-request-id,它是定位这一条请求的唯一标识。报障时请附上 x-request-id、出现时间(带时区)、模型 ID 与完整的报错原文——服务端故障在控制台不显示原文,排查以 x-request-id 为准。
curl -i https://api.hop-base.com/v1/models \
-H "Authorization: Bearer $HOPBASE_API_KEY"
# HTTP/2 200
# x-request-id: …部分模型响应会带有自身的限流头(x-ratelimit-*、anthropic-ratelimit-*),它们描述的不是你账户或密钥的上限,不要据此限流。
错误
OpenAI 协议的端点返回 {"error": {"message", "type", "code"}};/v1/messages 返回 Anthropic 结构 {"type": "error", "error": {"type", "message"}},没有 code。文案语言按 Accept-Language 返回,未指定时为英文——程序里请按 HTTP 状态码和 code 判断,不要匹配文案。
| 状态码 | 含义 | 能否重试 |
|---|---|---|
| 400 / 413 | 参数不合规 / 请求体超过 60 MB | 否,先改请求 |
| 401 | 没带密钥、密钥无效或已过期 | 否 |
| 402 | 余额或额度用完;视频提交时余额不足以覆盖在途预留 | 充值后 |
| 403 | 帐户或成员被停用、无权使用该分组 | 否 |
| 404 | 这把密钥的所有分组都不提供该模型或路径 | 否 |
| 429 | 帐户或密钥并发已达上限,或服务繁忙 | 按 Retry-After 重试 |
| 502 / 503 / 504 | 服务暂时不可用或超时 | 退避重试 |
流式请求一旦开始输出,HTTP 状态已是 200,之后的错误以事件下发,见流式事件。完整错误码清单与重试规则见错误码与重试。
并发与限流
HopBase 按同时在途的请求数限流,而不是按每分钟请求数:帐户默认同时在途 5 个请求;持续触顶时会按余额自动临时调高,长期调高可申请;单把密钥可在控制台另设上限,两者取小。超限的请求立即返回 429(user_concurrency_limit / apikey_concurrency_limit,带 Retry-After: 1 与 Retry-After-Ms),不会在服务端排队。
对话、生图、视频提交、/v1/messages/count_tokens 占并发;轮询任务与 GET /v1/models 不占。超时口径与客户端读超时建议见并发、超时与计费。
计费
请求成功按模型计价单位计费(token / 张 / 秒 / 字符);失败原则上不计费,流式中断按已产出部分计费;异步任务失败不计费。查余额用 GET /v1/usage,官方牌价见公开目录 GET /api/v1/models/pricing(字段说明)。
机器可读描述
/openapi.json:本节全部端点的 OpenAPI 3.1 描述,可导入 Postman、Apifox 或 SDK 生成器。/spec/models/index.json:每个生图模型一份请求体 JSON Schema,数字取自网关校验代码。- 请求构建器:在浏览器里按模型拼出合法的生图请求并生成代码。