# 模型与绘图参数

本章是[原生接口](https://api.hamubox.com/docs/novelai/native/)与[异步任务接口](https://api.hamubox.com/docs/novelai/tasks/)共用的参数说明。原生接口直接发送操作请求，异步接口将同一个操作请求放入 `payload`。先调用 `GET /v1/models` 确认当前本站 Key 可用的模型。

## 模型与功能

| 模型系列 | 普通模型 ID | 角色提示词 | 氛围参考 | 精准参考 | 生成过程 |
| --- | --- | --- | --- | --- | --- |
| V5 Curated / Full | `nai-diffusion-5-curated` / `nai-diffusion-5-full` | 支持 | 不支持 | 不支持 | 支持 |
| V4.5 Curated / Full | `nai-diffusion-4-5-curated` / `nai-diffusion-4-5-full` | 支持 | 使用编码 | 支持 | 支持 |
| V4 Curated / Full | `nai-diffusion-4-curated-preview` / `nai-diffusion-4-full` | 支持 | 使用编码 | 不支持 | 支持 |
| Anime V3 / Furry V3 | `nai-diffusion-3` / `nai-diffusion-furry-3` | 不支持 | 使用源图 | 不支持 | 不支持 |

以上系列均有文生图、图生图能力。局部重绘的实际模型按下表填写，不能随意拼接后缀。原生请求使用右列的 `model`；异步请求外层使用左列的 `model`，内层 `payload.model` 使用右列。

| 普通模型 / 异步外层 `model` | 局部重绘实际模型 |
| --- | --- |
| `nai-diffusion-5-full` | `nai-diffusion-5-full-inpainting` |
| `nai-diffusion-5-curated` | `nai-diffusion-4-5-curated-inpainting`，当前由 V4.5 Curated 执行 |
| `nai-diffusion-4-5-curated` / `nai-diffusion-4-5-full` | `nai-diffusion-4-5-curated-inpainting` / `nai-diffusion-4-5-full-inpainting` |
| `nai-diffusion-4-curated-preview` / `nai-diffusion-4-full` | `nai-diffusion-4-curated-inpainting` / `nai-diffusion-4-full-inpainting` |
| `nai-diffusion-3` / `nai-diffusion-furry-3` | `nai-diffusion-3-inpainting` / `nai-diffusion-furry-3-inpainting` |

可用性以当前 Key 的模型清单为准。V5 不接受氛围参考、精准参考、Variety+ 或 CFG Delay。角色提示词与图生图不是这两种参考功能，仍然可用。

## V5 Full 节约模式

V5 Full 可选择通常（High）或节约（Medium）。默认仍是通常模式；节约模式使用独立的蒸馏模型，不等同于把普通 V5 的步数减少到 14。

| 模式 | 原生请求 `model` / 异步 `payload.model` |
| --- | --- |
| 节约模式文生图、图生图 | `nai-diffusion-5-full-medium` |
| 节约模式局部重绘 | `nai-diffusion-5-full-medium-inpainting` |

异步请求外层 `model` 与 `payload.model` 均可填写上表对应的 Medium 模型 ID，任务、日志和返回结果会记录实际的 Medium 模型。授权、可用渠道与倍率仍沿用 `nai-diffusion-5-full`，不需要新增 Key 或另选分组。为兼容旧客户端，外层填写 `nai-diffusion-5-full`、内层填写对应 Medium ID 的方式仍然可用；V5 Curated 不支持节约模式。

- 固定 `parameters.steps: 14`、`parameters.sampler: "k_euler_ancestral"`；`cfg_rescale` 省略或为 `0`，不兼容的设置会在提交前拒绝。
- 使用官方固定 Heavy 负向预设，不支持自定义负面提示词或角色负面提示词。工作台会保留原输入，切回通常模式后恢复；需要抑制内容时可在正向提示词使用负权重，如 `-3::hat::`。
- 提示词引导强度、角色正向提示词、透明背景、图生图和局部重绘按 V5 Full 能力使用。流式接口也支持 Medium。
- 平台基础费和 Anlas 单价由站点配置，以报价接口返回的 `base_price_usd`、`anlas_unit_price_usd`、`group_ratio` 和 `estimated_cost_usd` 为准。默认普通生成及辅助操作基础费为 $0.003，V5 通常模式为 $0.01/张，V5 Full 节约模式为 $0.006/张，额外 Anlas 为 $0.004/Anlas，再应用生效倍率。实际结算采用提交时的价格快照，后续改价不影响已提交任务；BYOK 不收平台基础费及平台 Anlas 费用。官方宣称的使用额度节省比例不等于本站售价折扣。
- 当前仅由支持 Medium 的官方账户执行，不会自动替换成通常模型。平台官方可用额度不足时，提交可能被拒绝。

官方说明：[Effort 参数](https://docs.novelai.net/en/image/effort/)、[2026-10-08 公告](https://journal.novelai.net/novelai-diffusion-v5-full-effort-toggle/)。

### 提示词容量

NAI 工作台在提示词下方显示 token 用量和容量条。这是提示词上下文容量，不是计费 token，也不是可调的推理预算。

| 模型 | 提示词容量 |
| --- | --- |
| V5 Full（含节约模式） | 1471 token |
| V5 Curated | 703 token |
| V4 / V4.5 | 512 token |
| V3 | 225 token |

正向、负面提示词分别计算；支持角色的模型将基础提示词与实际提交的角色提示词合计，包含自动质量标签和负向预设。计算在本地浏览器的后台线程执行，不向外部发送提示词。

超出容量时会提示后段内容可能被模型忽略，但工作台不会截断输入，也不会修改 API 请求。容量提示参照官网当前编码器；复杂提示词的最终解释仍以上游模型为准。

## 生成参数

普通生成使用 `action: "generate"`，图生图使用 `"img2img"`，局部重绘使用 `"infill"`。通常模式异步文生图与图生图的外层 `model` 和 `payload.model` 一致；重绘及节约模式按上表填写。

| 操作请求内字段（异步时位于 `payload`） | 用途与边界 |
| --- | --- |
| `input` | 正向提示词 |
| `parameters.width` / `height` | 必填正整数，单位像素；总像素不超过 3,145,728。普通图生图必须为 64 的倍数，如 832×1216、1216×832、1024×1024；Max Enhance、局部重绘使用各自的尺寸规则 |
| `parameters.steps` | 必填，服务端边界为 0–50；通常使用 23 或 28 步，0 并不保证各模型可生成 |
| `parameters.n_samples` | 所有生成及报价入口均暂时只支持 1；省略时按单张估价，原生/异步透传不会自动补写此字段。建议显式传 `1`，需要多张时分别提交单张请求 |
| `parameters.params_version` | V5 使用 4，V4/V4.5/V3 示例采用 3 |
| `parameters.scale` | 提示词引导强度，例如 5；不是缩放图片倍数 |
| `parameters.sampler` / `noise_schedule` | 采样器与噪声计划，例如 `k_euler_ancestral` / `karras`；按模型支持情况传入 |
| `parameters.seed` | 具体的非负整数种子。需要随机时由客户端生成，不要照搬其他模型的 `-1` 约定 |
| `parameters.uc` | 负向提示词 |
| `parameters.image_format` | 流式请求可选 `png` / `webp`；未指定时主站流式默认请求 PNG |
| `parameters.image` / `mask` | 图生图源图、重绘遮罩；重绘需要两者，尺寸应与本次输入画布一致 |
| `parameters.strength` / `noise` | 图生图强度与噪声，通常在 0–1 内；按实际意图明确传值 |
| `parameters.img2img` | 图生图/重绘的 `strength`、`color_correct`；重绘还可传 `inpaintImg2ImgStrength` |

其他官方绘图参数保留在 `parameters` 对象中透传，显式 `0`、`false` 不会因默认值而被省略。透传不等于所有模型都支持同样参数；不要在 V5 请求中保留旧模型独有的参考或加速字段。

### 必填结构与提交校验

**即使没有角色提示词，普通 V5 和 V4.5 Full 文生图也需要结构化提示词。** 只发送 `input`、`uc`、宽高、步数和采样器并不完整。以下文生图行为已于 2026-10-13 至 14 日用官方上游实际生成验证：

| `action: "generate"` 的实际模型 | `v4_prompt` / `v4_negative_prompt` | 对象内部要求 |
| --- | --- | --- |
| V5 Full、V5 Curated、V4.5 Full | 两个对象都必填；分别省略会导致上游 HTTP 500 | 都必须包含对象 `caption` 和数组 `caption.char_captions` |
| V5 Full Medium | 实测允许省略任一完整对象 | 一旦传入对象，仍必须包含 `caption.char_captions`；省略内部数组会导致上游 HTTP 500 |

没有角色时使用 `char_captions: []`，不是 `null`、`{}`，也不要省略。平台在**创建任务、入队和预扣前**检查上述结构，缺失时返回 HTTP 400 与具体字段路径。同步和流式原生入口遵循相同规则，流尚未开始时仍返回 JSON 错误。

**普通图生图 `action: "img2img"` 也执行相同的提示词结构校验**：V5 Full、V5 Curated、V4.5 Full 必须提供两个对象；V5 Full Medium 允许省略完整对象，但传入时仍校验内部结构。此项补充用于防止不完整的图生图请求进入上游后仅返回笼统的 500；上表的逐项实测记录仍仅针对文生图，不表示每个图生图模型都已完成逐字段复测。其它模型、局部重绘以及 `upscaled_enhance: true` 的 Max Enhance 保留原来的提示词校验范围。

普通图生图的 `parameters.width` 和 `parameters.height` 必须是 **64 的正整数倍**。例如 `832×1110` 会在提交前返回 HTTP 400，明确指出 `parameters.height` 和收到的值 `1110`。请先将底图缩放或裁剪为所需合法尺寸，并填写对应宽高；平台不会自动缩放图片或静默修改尺寸。不要只依赖估价成功判断请求是否合法，报价仍允许按计费规则估算非对齐尺寸。Max Enhance、局部重绘、独立放大和 Director 不套用这项普通图生图限制。

V5 Full 最小文生图结构示例（原生请求直接发送；异步请求放入 `payload`）：

```json
{
  "model": "nai-diffusion-5-full",
  "action": "generate",
  "input": "1girl",
  "parameters": {
    "width": 512,
    "height": 512,
    "steps": 28,
    "n_samples": 1,
    "seed": 1,
    "scale": 5,
    "sampler": "k_euler_ancestral",
    "uc": "lowres",
    "v4_prompt": {
      "caption": { "base_caption": "1girl", "char_captions": [] }
    },
    "v4_negative_prompt": {
      "caption": { "base_caption": "lowres", "char_captions": [] }
    }
  }
}
```

这里需要区分三类参数，不能把所有参数缺失都解释为“官方必然返回 500”：

- **平台计费必填**：`width`、`height`、`steps`，用于预估和预扣；缺失会返回字段明确的 HTTP 400，不会提交生成。`model`、`action`、`parameters` 也必须完整，异步入口还要求外层 `model`、`operation`、`payload`。
- **已验证的上游结构要求**：上表中的提示词对象和角色数组。NAI 工作台已自动构造这些结构；直接对接 API 的客户端需要自己提供。OpenAI Images 兼容入口会从 `prompt`、`nai.uc` 构造结构，无需手工填写。
- **不要误判为必填**：普通 V5 Full 文生图实测可省略 `n_samples`；单独省略 `sampler`、`scale`、`seed` 或提示词位置开关也可以生成。省略这些会依赖上游默认行为，建议为可复现性明确传值。只有完整结构化提示词时，才可参考实测结果省略对应的 `input` / `uc`，不建议混用冲突的两份文案。

`params_version`、`noise_schedule`、`image_format` 在本次 V5 Full 非流式最小请求中未填写也能生成。这些结果不代表所有模型、所有模式都具有相同默认值。**估价成功不代表请求结构完整**：报价入口仍允许只传计费所需参数，正式提交前必须补齐生成字段。

### 角色提示词

V4、V4.5、V5 使用 `v4_prompt` 和 `v4_negative_prompt`，V5 的字段名仍为 `v4_prompt`。`caption.base_caption` 应与正向 `input`、负向 `uc` 各自一致。每个角色用 `char_captions` 的一个条目表示，正负向角色顺序对应：

```json
{
  "v4_prompt": {
    "caption": {
      "base_caption": "two characters, standing in a garden",
      "char_captions": [
        { "char_caption": "short blue hair, white jacket", "centers": [{ "x": 0.25, "y": 0.5 }] },
        { "char_caption": "long red hair, black jacket", "centers": [{ "x": 0.75, "y": 0.5 }] }
      ]
    },
    "use_coords": true,
    "use_order": true
  },
  "v4_negative_prompt": {
    "caption": {
      "base_caption": "lowres, blurry",
      "char_captions": [
        { "char_caption": "hat", "centers": [{ "x": 0.25, "y": 0.5 }] },
        { "char_caption": "glasses", "centers": [{ "x": 0.75, "y": 0.5 }] }
      ]
    },
    "use_coords": false,
    "use_order": false
  }
}
```

以上片段放入 `payload.parameters`。坐标为 0–1 的归一化位置；自动位置使用 `use_coords: false`。没有角色时传空 `char_captions` 即可。本站不替客户端自动拼接质量词或负向预设，最终完整提示词由请求决定。

### 素材输入与参考

`image`、`mask`、`director_reference_images[]` 可使用可访问的 HTTP(S) 图片 URL、图片 Data URL 或原始 Base64。不要传 `blob:` URL 或本地文件路径。提交后，服务端整理素材并转换成上游所需格式，日志保留文件引用，不写入整段图片 Base64。

第三方 URL 必须能由服务器直接下载图片，不依赖登录 Cookie、防盗链 Referer 或额外请求头。支持 PNG、JPEG、WebP、GIF、BMP；单份输入不超过 64 MiB，单次请求全部输入不超过 256 MiB，最多 32 份归档素材。外部图片会先下载、校验并归档，再参与生成；每份下载限时 30 秒，并检查重定向及网络访问安全。本站文件 URL 仍须属于当前用户且未删除，不能用外链下载绕过权限。

链接失效、下载失败、非图片或超限时返回 HTTP 400，错误码 `invalid_input_asset`，消息指出对应素材（如 `precise-reference input 1` 表示 `director_reference_images[0]`）。此时不会提交生成任务；若已预扣，将执行退还。第三方站点无法直连时，请先上传素材或改传 Data URL / Base64。文件存储或数据库故障仍返回 HTTP 500，不属于图片参数错误。

- **图生图 / 局部重绘**：使用 [图生图请求](https://api.hamubox.com/docs/examples/novelai-img2img.json) / [重绘请求](https://api.hamubox.com/docs/examples/novelai-inpaint.json)。图生图不能误用 `-inpainting` 模型。
- **V4/V4.5 氛围参考**：先以 `operation: "encode-vibe"` 提交[编码请求](https://api.hamubox.com/docs/examples/novelai-vibe.json)，再将 `result.encoded_vibe` 放入生成请求的 `parameters.reference_image_multiple[]`，以 `reference_strength_multiple[]` 对应设置强度。编码与模型相关，不要跨模型复用。编码是二进制数据的 Base64，并不是一张图片。
- **V3 氛围参考**：`reference_image_multiple[]` 使用源图片输入，推荐预处理成 448×448；同时传对应的 `reference_strength_multiple[]`、`reference_information_extracted_multiple[]`。不调用 `encode-vibe`。
- **V4.5 精准参考**：使用 `director_reference_images[]`，并对应传 `director_reference_descriptions[]`、`director_reference_strength_values[]`、`director_reference_secondary_strength_values[]` 和 `director_reference_information_extracted[]`。各数组按同一素材顺序对应。素材会由服务端预处理为模型需要的尺寸，留档保留原素材。

氛围参考、精准参考的当前任务计费边界各为最多 16 项，具体能否组合仍取决于模型。V5 两者均不支持。异步任务需要提供实际素材数据或文件地址；原生接口另支持 multipart 与按用户隔离的缓存键，见[官方协议兼容](https://api.hamubox.com/docs/novelai/native/#参考素材缓存)。

也可以先使用[素材上传接口](https://api.hamubox.com/docs/references/#上传素材)获得文件 URL，再填入 `parameters.image`、`parameters.mask` 或源图片数组。临时上传与用户资产库的可见范围见[常见问题](https://api.hamubox.com/docs/novelai/faq/#参考素材是否进入资产库)。

## Director、放大与氛围编码

### Enhance 增强

Enhance 属于图生图重采样，不是独立 Upscale。使用 `operation: "generation"`、`payload.action: "img2img"`，通过 `parameters.image`、`strength`、`noise` 和输出宽高控制；它会重新生成细节。

V5 还支持 `parameters.upscaled_enhance: true`（Max Enhance）：请求宽高保留输入尺寸，输出最多放大 2 倍并限制到 3,145,728 像素，按 32 像素对齐。估价按输出尺寸计算，不能用输入小图尺寸判断免费额度。该模式不能与局部重绘混用；最终实际尺寸以结果文件为准。

### 独立图像工具

这些操作不提供中间生成过程。异步入口通过 `operation` 区分，原生入口通过路径区分；请求内容相同，只有外层包装不同。

| 异步 `operation` | 原生路径（接在 `/v1/novelai` 后） | 操作参数 |
| --- | --- | --- |
| `director` | `/ai/augment-image` | `req_type`、`image`、`width`、`height`；工具可能另需 `prompt`、`defry`、`emotion` |
| `upscale` | `/ai/upscale` | `image`、`model`、`declared_blur_sigma`；固定 2 倍，输入不超过 3,145,728 像素。Base64 图片自动读取尺寸；旧参数 `width`、`height`、`scale=2` 仍可传入 |
| `encode-vibe` | `/ai/encode-vibe` | `model`、`image`、可选 `information_extracted`（大于 0 且不超过 1）；异步时 `model` 与外层一致 |

Director 的 `req_type` 支持 `bg-removal`、`declutter`、`declutter-keep-bubbles`、`lineart`、`sketch`、`colorize`、`emotion`。Director 和放大操作的外层 `model` 用于选择可用的 NovelAI 服务，不代表所有工具都由该绘图模型执行。

各操作均有独立的[原生请求示例](https://api.hamubox.com/docs/novelai/native/#完整请求示例)和[异步请求示例](https://api.hamubox.com/docs/novelai/tasks/#其它操作示例)。费用、结果元数据与留档见[常见问题](https://api.hamubox.com/docs/novelai/faq/)。