HopBase 文档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-你的密钥不支持 x-goog-api-key 与 URL 参数 ?key=。GET /v1/usage 只认 Authorization: Bearer。
每把密钥绑定一个分组（例如「Codex Pro」「Claude Max (官号满血版)」「GPT Image 全系」），只能调该分组提供的模型和该分组协议的端点：Claude 密钥调 /v1/chat/completions 返回 404「当前平台不支持该 API 路径」，对话分组的密钥调图片模型返回 404 model_not_found。同一个项目既要对话又要生图时，请建两把密钥分别放进不同的环境变量。可用模型以这把密钥调 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，数字取自网关校验代码。- 请求构建器：在浏览器里按模型拼出合法的生图请求并生成代码。