鉴权与模型可用性

请求头

Authorization: Bearer sk-your-api-key
Content-Type: application/json

使用本站 API Key，不是网站登录密码、Cookie 或模型供应商的 Key。查询任务同样需要鉴权，推荐始终使用提交时的 Key。

分组怎么选择

分组在创建 API Key 时选择。通常不需要在 JSON 请求体添加 group。更换分组时使用该分组的 Key。

分组决定可用模型和适用价格。本站内部的模型路由与账户调度不属于客户端请求参数，客户端只需传文档中的公开模型 ID。

同名模型不等于所有分组都拥有完全相同的能力。例如，本版 nano-banana-pro 章节描述 default 分组的 1K / 2K 规格，不能据此推断其他分组也相同。

查询模型清单

curl 'https://api.hamubox.com/v1/models' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"

响应是包含 data 数组的对象，模型名称位于 data[].id。清单会随 Key 的权限、可用线路与模型上下架变化。

这不是完整的模型参数 Schema。不要从名称猜测参考素材数量、分辨率和费用；使用对应的模型章节。也不要依赖 owned_by 等描述性字段做业务路由。

常见鉴权问题

现象	检查方向
HTTP 401	Key 是否完整、有效、过期；是否误填登录令牌
模型不在清单	Key 分组、模型权限、模型是否已下架
HTTP 403	当前操作或模型访问权限
HTTP 429	降低请求频率；检查模型与账户限流
查询返回 404	任务 ID、图片 / 视频查询路径、访问账户是否一致

Key 失效时应暂停轮询并让操作者处理鉴权问题，不要自动退出整个网站或不断重试鉴权失败请求。