异步任务接口

自行开发应用时，推荐提交任务后查询结果；需要生成过程时再增加 SSE。鉴权使用本站 API Key，所有请求均携带 Bearer Token。

方法	路径	返回
POST	`/v1/novelai/estimate`	费用预估，不创建生成任务
POST	`/v1/novelai/tasks`	HTTP 202，返回任务 ID
GET	`/v1/novelai/tasks/{task_id}`	状态、错误、文件与结算信息
GET	`/v1/novelai/tasks/{task_id}/events`	SSE 状态、预览和成图事件

提交任务

请求外层是本站任务格式；payload 是对应的官方操作请求。通用的绘图参数放在 payload.parameters，不要放到外层。

字段	说明
`model`	必填。当前 Key 可用的 NovelAI 模型 ID
`operation`	必填。`generation`、`director`、`upscale` 或 `encode-vibe`
`payload`	必填。对应操作的完整请求对象
`stream`	可选布尔值，默认关闭。仅 V4 及更新模型的 `generation` 可用；POST 仍返回 JSON 任务

V5 单图示例，开启生成过程。下载novelai-generate.json后直接发送：

{
  "model": "nai-diffusion-5-curated",
  "operation": "generation",
  "stream": true,
  "payload": {
    "input": "a blue ceramic cup on a wooden table, soft daylight, illustration",
    "model": "nai-diffusion-5-curated",
    "action": "generate",
    "parameters": {
      "params_version": 4,
      "width": 832,
      "height": 1216,
      "steps": 23,
      "scale": 5,
      "sampler": "k_euler_ancestral",
      "noise_schedule": "karras",
      "seed": 42,
      "n_samples": 1,
      "image_format": "png",
      "uc": "lowres, blurry",
      "v4_prompt": {
        "caption": {
          "base_caption": "a blue ceramic cup on a wooden table, soft daylight, illustration",
          "char_captions": []
        },
        "use_coords": false,
        "use_order": true
      },
      "v4_negative_prompt": {
        "caption": {
          "base_caption": "lowres, blurry",
          "char_captions": []
        },
        "use_coords": false,
        "use_order": false
      }
    }
  }
}

curl --fail-with-body 'https://api.hamubox.com/v1/novelai/tasks' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @novelai-generate.json

HTTP 202 示例，服务端还可能返回 usage 等字段：

{
  "id": "task_your_existing_id",
  "object": "novelai.image.task",
  "created_at": 1790000000,
  "updated_at": 1790000000,
  "status": "queued",
  "progress": 0,
  "model": "nai-diffusion-5-curated",
  "operation": "generation"
}

开启 stream 不会让这个 POST 变成 SSE。保存 id 后再订阅事件。

参数错误

可提前识别的错误在入队、预扣前返回 HTTP 400，不创建任务。例如请求已包含正向结构，但漏掉负向结构：

{
  "error": {
    "code": "invalid_request",
    "type": "novelai_error",
    "message": "invalid NovelAI generation parameters: parameters.v4_negative_prompt is required; provide caption.char_captions: [] when there are no characters"
  }
}

错误里的 parameters.* 指 payload.parameters.*。例如 parameters.v4_prompt.caption.char_captions must be an array 表示应补上角色数组，没有角色时填写 []；missing required pricing parameters: parameters.steps 表示缺少用于计费的步数。

修正字段后再提交，不要原样自动重试 400。模型范围、节约模式例外与完整结构见必填结构与提交校验。已被接受的任务若后续失败，仍通过任务查询返回 failed，不要将其与提交前拒绝混淆。

查询与恢复

每隔 5 秒查询同一个任务：

curl --fail-with-body \
  'https://api.hamubox.com/v1/novelai/tasks/task_your_existing_id' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"

`status`	客户端行为
`queued` / `in_progress`	继续等待；也可以订阅 SSE
`completed`	停止查询；图片读取 `result.images[].url`，氛围编码读取 `result.encoded_vibe`
`failed`	停止查询，展示 `error.message`，保留 `id` 和 `error.code`
`unknown`	不当作成功或失败；保留任务 ID，稍后查询或联系支持

图片文件对象包含 id、url、filename、mime_type、size，可能还包含 md5。这与通用图片接口的 outputs[] 不同。读取结果 URL 时不要携带本站 Authorization。最终图片进入发起用户的资产库，中间预览不入库。

刷新、断线或切换页面后，继续查询同一个任务。通过原生接口或 OpenAI Images 兼容入口提交时，保存响应头 X-NovelAI-Task-Id，也能在这里查询。客户端断开连接不会取消已接受的任务。

排队等待默认最多 10 分钟，管理员可以在 NAI 运营设置中调整。达到等待上限仍未开始的任务返回 failed / queue_timeout，退回预扣；执行中的任务使用单独的运行超时。

幂等提交

提交任务、原生生成及 OpenAI Images 兼容入口均接受可选的 Idempotency-Key 请求头。每次用户主动生成时创建一个新值；网络重试保留原值与原请求内容，最多 128 字节。

curl --fail-with-body 'https://api.hamubox.com/v1/novelai/tasks' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-unique-image-request-001' \
  --data-binary @novelai-generate.json

相同用户、操作、标识和请求内容：取回原任务或原结果，不再次生成或预扣。分组、模型、素材、提示词及参数变化会视为不同内容。
同一标识对应不同内容：HTTP 409，idempotency_conflict。
首次请求尚在准备中：HTTP 409，idempotency_in_progress，按 Retry-After 等待后用同一标识重试。若长时间未能确认是否接受，请保留标识与任务 ID 联系支持，不要换标识重复生成。
首次请求在任务接受前已失败：HTTP 409，idempotency_rejected。先解决原错误，再由用户主动发起新的生成。
原任务已失败：仍返回原任务的失败状态；重新生成必须使用新的标识。

不提供此请求头的旧客户端仍按每次 POST 创建任务。不能仅依靠相同提示词去重，因为用户可能确实希望连续生成多张。原生错误继续使用其原有的字符串错误格式。

费用预估

同一个完整请求可先发送到估价接口：

curl --fail-with-body 'https://api.hamubox.com/v1/novelai/estimate' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @novelai-generate.json

读取 usage.estimated_cost_usd 与 usage.estimated_anlas。估价不启动生成，不代表锁定报价。正式任务提交时预扣，终态返回 usage.actual_cost_usd 等结算信息；尚未返回的字段不能当作零。Anlas 与本站美元余额是不同单位，免费 Anlas 不表示本站服务免费。

报价接口也兼容只包含计费参数的请求，不要求完整的 v4_prompt / v4_negative_prompt。获得报价不代表请求可直接生成；提交到 /tasks 前仍需补齐对应模型的提示词结构。

其它操作示例

下列文件都包含完整的 model、operation、payload，可使用上面的提交命令，替换 JSON 文件名即可。需要素材的示例先将 https://example.com/... 替换为可访问的真实文件 URL。

操作	请求 JSON	成功结果
图生图	novelai-img2img.json	`result.images[]`
局部重绘	novelai-inpaint.json	`result.images[]`
Director 提取线稿	novelai-director.json	`result.images[]`
放大	novelai-upscale.json	`result.images[]`
氛围编码	novelai-vibe.json	`result.encoded_vibe`，编码二进制的 Base64，不是图片

Director、放大与氛围编码不支持 stream。模型能力、素材字段、角色提示词和操作边界统一见模型与绘图参数。

也可以使用Python 异步客户端：

python client.py novelai novelai-generate.json
python client.py novelai --task-id task_your_existing_id