# NovelAI 接入概览

NovelAI 提供专业绘图参数、角色提示词、图生图、局部重绘和图片工具，使用独立的 `/v1/novelai` 接口。它不通过通用的 `/v1/image/generations` 提交。

## 选择接入方式

| 场景 | 使用方式 | 从这里开始 |
| --- | --- | --- |
| 已有支持 NovelAI 的第三方客户端 | 替换服务地址和 Key，保留官方请求字段与 ZIP / 二进制响应 | [客户端接入](https://api.hamubox.com/docs/novelai/clients/) |
| 自行开发应用，需要任务 ID、轮询与稳定结果链接 | 提交异步任务，再查询状态与结算 | [异步任务接口](https://api.hamubox.com/docs/novelai/tasks/) |
| 需要边生成边预览，尽早收到完整成图 | 异步任务加 SSE，或官方格式 MessagePack 流 | [流式生成与恢复](https://api.hamubox.com/docs/novelai/streaming/) |

两套协议使用同一套模型、计费与结果留存。绘图参数集中在[模型与绘图参数](https://api.hamubox.com/docs/novelai/models/)维护；各协议章节提供各自完整的请求示例。

## 地址与鉴权

第三方原生客户端配置：

```text
Base URL: https://api.hamubox.com/v1/novelai
API Key: 本站创建的 API Key
```

客户端在 Base URL 后追加官方路径。例如 `/ai/generate-image` 的最终地址是：

```text
https://api.hamubox.com/v1/novelai/ai/generate-image
```

所有请求携带 `Authorization: Bearer <本站 API Key>`。不要填写 NovelAI 官网密码或 `pst-…` 密钥。异步接入直接使用本章给出的完整路径，不要重复拼接 `/v1/novelai`。

先确认当前 Key 可用的模型：

```bash
curl --fail-with-body 'https://api.hamubox.com/v1/models' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"
```

## 接入范围

支持 V3、V4、V4.5、V5 的绘图操作与已列出的原生路径，包括生成、Director Tools、放大、氛围编码、标签建议、报价和客户端账户显示兼容。不同模型的功能不完全相同，以[能力表](https://api.hamubox.com/docs/novelai/models/#模型与功能)和当前 Key 的模型清单为准。

不代理 NovelAI 登录、支付、故事、文本生成、语音或云端图片库。账户接口返回本站的兼容显示信息，不返回平台上游账号的余额、电量或会员信息。

每次生成暂时只支持一张；`n_samples` 省略或填 `1`。需要多张时分别提交，详情见[生成张数](https://api.hamubox.com/docs/novelai/native/#生成张数与费用)。

## 接入前需要处理的边界

- 素材可用文件 URL、受支持的 Base64 / Data URL 或原生 multipart；临时上传、有效期与可见范围见[参考素材](https://api.hamubox.com/docs/references/)。
- 提交后立即保存任务 ID；原生请求读取 `X-NovelAI-Task-Id` 响应头。断线后查询同一任务，不自动重复 POST。
- 原生流是长度帧 MessagePack；异步事件是 SSE。两者的解析器不能混用。
- 收到完整成图即可展示，但稳定文件链接和最终费用仍以任务查询为准。

给自动化工具或 LLM 接入时，提供[OpenAPI](https://api.hamubox.com/docs/openapi.json)和[文档索引](https://api.hamubox.com/docs/llms.txt)。常见的单位、缓存和素材保存问题集中在[常见问题](https://api.hamubox.com/docs/novelai/faq/)。