API 接口面对齐¶
对本服务器与 NovelAI 已发布 API 文档的审计,并针对真实端点做了
在线验证。当生成请求开始因校验错误而失败、NovelAI 宣布 API 变更,或
发布前涉及 nai/ 时,请重新运行该审计。
官方文档究竟是什么¶
URL |
提供的内容 |
|---|---|
|
Swagger UI。其内联配置指向 |
|
真正的规范:Swagger 2.0,27 条路径,57 个定义,标题为 “Omegalaser API”。 |
|
同一份规范的逐字节相同副本。 |
|
Swagger UI,其 |
|
“Observability API”(错误追踪),与图像生成无关。 |
|
产品指南(194 页)。它们描述的是功能与 UI 设置,而不是端点或字段名;从不提及 |
用项目自带的浏览器指纹客户端抓取该规范(Cloudflare 会拦截普通客户端):
from novelai_image_mcp.nai.http import create_http_client
async with create_http_client(timeout=60) as client:
spec = (await client.get("https://image.novelai.net/docs/doc.json")).json()
该规范不是字段白名单¶
image.RequestParameters 省略了本客户端会发送、且 API 会接受的字段 ——
characterPrompts、autoSmea、ucPresetId、qualityPresetId(V5)、
normalize_reference_strength_multiple、inpaintImg2ImgStrength、
legacy_uc、参数级 use_coords —— 并且把 model、
sampler 与 noise_schedule 标注为不带枚举的普通字符串。请把
该规范视为存在哪些路径与响应结构的权威,
把在线 API 视为哪些字段可用的权威。
路径清单(文档中记载 27 条)¶
2026-10-10 用真实账户验证(记录了 Anlas 前后变化)。
文档记载的路径 |
本服务器 |
实测结果 |
|---|---|---|
|
V3 / Furry ZIP 路径( |
使用 |
|
V4 / V4.5 / V5 msgpack 路径 |
200( |
|
|
200, |
|
|
在本主机上仅 V5 模型返回 200;旧的 |
|
|
|
|
|
200(二进制 vibe 文件,由客户端做 base64 编码) |
|
|
200 |
|
|
200 |
|
— |
200(邮箱/验证/封禁状态) |
|
— |
200(priority 补充) |
|
— |
使用 persistent token 时 401 |
|
— |
使用 persistent token 时 401 |
|
— |
文本生成;不在本图像服务器的范围内 |
|
— |
OpenAI 兼容的文本 API;对本账户 |
|
— |
账户/产品端点;本审计从不调用其中的变更操作与私有数据 |
|
|
不在该规范中。 在 |
改变本代码库的发现¶
/ai/upscale已迁移且仅支持 V5。 该端点在image.novelai.net上,接收{image, model, declared_blur_sigma},并 对每个 V3/V4/V4.5 模型都以 “model … doesn’t support standalone upscaling” 拒绝。此前的实现向api.novelai.net/ai/upscalePOST{image, width, height, scale},该地址现在返回 404 —— 该 工具当时是坏的。已通过upscale()修复:它向 image 主机发起请求, 发送文档记载的请求体,把模型默认为NOVELAI_UPSCALE_MODEL(nai-diffusion-5-full),并拒绝除 4× 步进之外的任何值(该 API 未暴露 factor)。suggest_tags返回{tag, count, confidence},而不是文档声称的{description, text, count}结构。schemas.TagSuggestion现在与线上字段一致(带extra="allow",因此上游新增字段可以保留)。/ai/generate-image(ZIP)对 V4/V4.5 模型返回 500 —— 这些模型必须 使用/ai/generate-image-stream。客户端已按模型家族路由 (is_v4_model()),因此无需改动。
有意未验证的内容¶
emotionDirector 工具:对没有人脸的合成图像该请求返回 500; 其余五个req_type值返回 200。需要一张人像才能确认。任何会变更账户状态的操作(
/user/consent、subscription/bind、create-persistent-token、objects/*删除)—— 按设计不在范围内。/user/giftkeys与/user/clientsettings对 persistent token 返回 401;要记录其结构需要 session token。