跳转到内容
HamuBox API

客户端接入

客户端必须允许修改服务地址与 API Key，且不能强制要求先登录 NovelAI 官网。使用官方 NovelAI 格式时按下方配置；只支持 OpenAI 图片格式时，可使用 OpenAI Images 兼容入口。不能修改地址或强制要求 pst- 前缀的客户端，不能保证只改地址就能接入。

通用配置

章节：通用配置
客户端设置填写内容
NovelAI API / 图片服务 Base URLhttps://api.hamubox.com/v1/novelai
API Key / Bearer Token本站 API Key
生成张数1
模型GET /v1/models 返回的可用 NovelAI 模型
流式生成客户端支持官方 MessagePack 且选择 V4 或更新模型时可启用

若客户端分别配置账户服务和图片服务地址，两处都填写上述 Base URL。最终生成请求应为 /v1/novelai/ai/generate-image 或 /v1/novelai/ai/generate-image-stream；不能丢掉前缀，也不能重复追加 /v1/novelai。

本站不代理官网登录、文本或语音等非绘图能力。不要把本站 Key 发送到 NovelAI 官网或第三方结果下载地址。

先确认配置，再生成

章节：先确认配置，再生成

这些检查不发起图片生成：

  1. 使用本站 Key 调用 GET https://api.hamubox.com/v1/models，确认有目标 NovelAI 模型。
  2. 调用 GET https://api.hamubox.com/v1/novelai/user/data，确认鉴权与账户显示兼容。
  3. 按原生报价格式调用 /v1/novelai/ai/generate-image/request-price，确认当前模型与参数能估价。
  4. 检查客户端生成地址、请求格式与单图设置，然后由使用者决定是否提交一次实际生成。

账户接口通过，不等于该客户端的每项功能都兼容。完整接入还应核对 ZIP 解包、流式帧解析、图生图 / 遮罩上传、缓存失效补传、模型切换和断线后任务查询。

当前验证范围

章节：当前验证范围

本站接口已有请求规范化、模型映射、计费边界和示例合同测试。文档提供异步 Python 示例与原生 MessagePack 示例作为接入参考。

下面的第三方客户端核对基于指定版本源码和本站协议回归，不代表全部功能已经完成实际付费生成验收。智绘姬 3.1.5 曾在客户端临时兼容补丁下完成单张 V5 Full 出图；本站兼容层更新后的原版插件仍需实际客户端验收。

客户端源码核对版本配置与边界
智绘姬 st-chatu83.1.5，b688a65NovelAI → 浏览器 → 其他站点；Base URL 使用 /v1/novelai，支持 Bearer 与 ZIP。同步请求固定携带的 parameters.stream: "msgpack" 由本站兼容处理，仍返回 ZIP。关闭插件自己的云端排队；超时后先到任务日志核对，不要直接重发。
柏宝绘 ST-BaiBai-Image0.3.2，1187528新增 NovelAI 第三方接入点，Base URL 使用 /v1/novelai。兼容同步 msgpack 提示、空参考数组及其 /ai/user/subscription 连接检查路径。V5 请关闭 Vibe；首次测试关闭自动生成 tag、自动生成图片，并发设为 1。插件网络重试未发送幂等键，超时后不要继续反复生成。
NovelAI Image Direct1.1.1图像与账户地址均使用 /v1/novelai；V5 界面和完整生成仍需客户端实测。
Quick Image Gen3.5.0选择 OpenAI 图片代理、Base URL 使用 /v1、模型使用本站 NAI ID，每次一张。其另一个 NAI JSON 代理模式不能直接接收原生 ZIP。
Aaalice NAI Launcher源码 c648ee6第三方 API 登录，主 API 与图片 API 均使用 /v1/novelai；发行版是否包含这些设置需核对。
SillyTavern 内置生图扩展1.18.0内置 NovelAI 和 OpenAI 生图分支使用固定官方地址。仅改聊天反代地址不会改变图片请求，需使用支持自定义图片地址的扩展。

浏览器直连使用 Bearer Token，请不要设置 credentials: 'include'。本站跨域预检明确允许 Authorization、Content-Type、Idempotency-Key，并公开任务 ID 与恢复相关响应头。自建客户端应保存生成意图的幂等标识，见幂等提交。

常见兼容差异

章节：常见兼容差异
  • 同步请求中带有 msgpack：本站只在 /ai/generate-image 和 /ai/generate-image/request-price 忽略值恰为字符串 "msgpack" 的 parameters.stream；同步生成仍返回 ZIP，报价仍返回 JSON。其他无效值不会被静默忽略；异步 /tasks、/estimate 的显式流式冲突校验不变。
  • 未开启参考却发送 []：空 Vibe / 精准参考数组按未使用该能力处理，与省略字段或 null 一样。实际非空参考仍受模型能力限制，错误类型不能替代数组。
  • V4/V4.5 的 Vibe 返回 invalid_input_asset：parameters.reference_image_multiple 和 parameters.reference_image 要填 Vibe 编码，不能直接填 JPEG、PNG 等原图的 Base64。先调用 /v1/novelai/ai/encode-vibe，将返回的编码二进制转为 Base64 后再生成。本站在预扣费前检查可识别的图片内容，返回 HTTP 400 和具体字段位置；已登记的编码文件 URL 同样检查实际内容，V3 仍可直接使用原图。此检查不保证所有未知二进制都是有效编码。
  • 显示 Anlas 但数值与官网不同：这里是本站余额的兼容显示单位，含义见账户与报价。
  • 缓存失效：收到 INVALID_CACHE_KEYS 后补传对应素材；不要直接丢掉参考图重试。
  • 流式结果打不开：MessagePack 是有长度前缀的二进制事件流，不能作为 ZIP / PNG 保存，见帧格式。
  • 连接超时：先查询 X-NovelAI-Task-Id 指向的任务；不要自动再提交一笔生成。
  • V5 的旧参考功能不可用：V5 不支持氛围参考和精准参考，图生图仍可用；按模型能力调整请求。