# 客户端接入

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

## 通用配置

| 客户端设置 | 填写内容 |
| --- | --- |
| NovelAI API / 图片服务 Base URL | `https://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. 按[原生报价格式](https://api.hamubox.com/docs/novelai/native/#账户与报价)调用 `/v1/novelai/ai/generate-image/request-price`，确认当前模型与参数能估价。
4. 检查客户端生成地址、请求格式与单图设置，然后由使用者决定是否提交一次实际生成。

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

## 当前验证范围

本站接口已有请求规范化、模型映射、计费边界和示例合同测试。文档提供[异步 Python 示例](https://api.hamubox.com/docs/examples/client.py)与[原生 MessagePack 示例](https://api.hamubox.com/docs/examples/novelai-stream.py)作为接入参考。

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

| 客户端 | 源码核对版本 | 配置与边界 |
| --- | --- | --- |
| 智绘姬 st-chatu8 | 3.1.5，`b688a65` | NovelAI → 浏览器 → 其他站点；Base URL 使用 `/v1/novelai`，支持 Bearer 与 ZIP。同步请求固定携带的 `parameters.stream: "msgpack"` 由本站兼容处理，仍返回 ZIP。关闭插件自己的云端排队；超时后先到任务日志核对，不要直接重发。 |
| 柏宝绘 ST-BaiBai-Image | 0.3.2，`1187528` | 新增 NovelAI 第三方接入点，Base URL 使用 `/v1/novelai`。兼容同步 `msgpack` 提示、空参考数组及其 `/ai/user/subscription` 连接检查路径。V5 请关闭 Vibe；首次测试关闭自动生成 tag、自动生成图片，并发设为 1。插件网络重试未发送幂等键，超时后不要继续反复生成。 |
| NovelAI Image Direct | 1.1.1 | 图像与账户地址均使用 `/v1/novelai`；V5 界面和完整生成仍需客户端实测。 |
| Quick Image Gen | 3.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 与恢复相关响应头。自建客户端应保存生成意图的幂等标识，见[幂等提交](https://api.hamubox.com/docs/novelai/tasks/#幂等提交)。

## 常见兼容差异

- **同步请求中带有 `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 但数值与官网不同**：这里是本站余额的兼容显示单位，含义见[账户与报价](https://api.hamubox.com/docs/novelai/native/#账户与报价)。
- **缓存失效**：收到 `INVALID_CACHE_KEYS` 后补传对应素材；不要直接丢掉参考图重试。
- **流式结果打不开**：MessagePack 是有长度前缀的二进制事件流，不能作为 ZIP / PNG 保存，见[帧格式](https://api.hamubox.com/docs/novelai/streaming/#messagepack-帧格式)。
- **连接超时**：先查询 `X-NovelAI-Task-Id` 指向的任务；不要自动再提交一笔生成。
- **V5 的旧参考功能不可用**：V5 不支持氛围参考和精准参考，图生图仍可用；按[模型能力](https://api.hamubox.com/docs/novelai/models/)调整请求。