流式生成与恢复

本站提供两种流式接法。新应用建议使用异步任务加 SSE，方便持久化任务 ID 和断线恢复；已有支持官方流式格式的客户端可以使用 /v1/novelai/ai/generate-image-stream，客户端 Base URL 填写 https://api.hamubox.com/v1/novelai。

两者都使用本站 API Key。仅 V4、V4.5、V5 的生成操作可用，每次请求只生成一张，parameters.n_samples 省略或填写 1；模型和参数限制见模型与绘图参数。V3、Director、放大和氛围编码不提供中间生成过程。

异步任务加 SSE

按异步任务示例先 POST /v1/novelai/tasks，请求顶层添加 "stream": true；立即保存 HTTP 202 返回的 id。随后订阅：

curl --no-buffer --fail-with-body \
  'https://api.hamubox.com/v1/novelai/tasks/task_your_existing_id/events' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Accept: text/event-stream'

响应为 text/event-stream，事件的 data 是 JSON：

事件	data 内容	客户端处理
state	与 GET 任务相同的完整响应	更新状态；completed / failed 停止订阅
preview	step、sample、image（图片 Data URL）	临时预览，不能当成最终结果
image	sample、filename、image（完整成图 Data URL）	可立即清晰显示和下载；继续等待归档/结算状态

step、sample 从 0 开始。以 : 开头的注释是心跳。中间帧可能被合并或跳过，不保证每一步都有事件；没有预览也不表示生成失败。只做状态订阅而未在提交时开启 stream，不会把普通任务变成流式生成。

浏览器原生 EventSource 不能直接设置 Authorization 请求头，建议使用 fetch 读取响应流并按 SSE 规则解析。不要把 API Key 放进 URL。支持跨网络 chunk 累积文本，遇到空行才结束一个事件，最终图的 Data URL 可能很长。

官方格式入口

POST /v1/novelai/ai/generate-image-stream 使用官方生成 JSON，不包含异步接口的 payload、operation 外层包装：

novelai-native-stream.json

{
  "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,
    "stream": "msgpack",
    "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 --no-buffer \
  'https://api.hamubox.com/v1/novelai/ai/generate-image-stream' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @novelai-native-stream.json \
  --dump-header stream-headers.txt --output result.msgpack

result.msgpack 是带长度帧的事件流，不是 PNG，也不是 ZIP。不要直接改名成图片。

服务端在响应头 X-NovelAI-Task-Id 中返回本站任务 ID。客户端应在读图片前就保存它，以便查询 /v1/novelai/tasks/{task_id}。本站原生入口也会创建任务记录，并使用相同的计费、留档和资产入库流程。

Multipart 素材

支持 multipart/form-data：request 字段为 JSON 文本或 JSON Blob，其余字段是图片文件。JSON 中的 parameters.image / mask 指向对应字段名，例如：

request.json

{
  "input": "a blue ceramic cup, watercolor illustration",
  "model": "nai-diffusion-5-curated",
  "action": "img2img",
  "parameters": {
    "params_version": 4,
    "width": 832,
    "height": 1216,
    "steps": 23,
    "scale": 5,
    "sampler": "k_euler_ancestral",
    "noise_schedule": "karras",
    "seed": 42,
    "n_samples": 1,
    "stream": "msgpack",
    "image_format": "png",
    "image": "source_image",
    "strength": 0.6,
    "noise": 0
  }
}

curl --fail-with-body --no-buffer \
  'https://api.hamubox.com/v1/novelai/ai/generate-image-stream' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -F '[email protected];type=application/json' \
  -F '[email protected];type=image/png' \
  --dump-header stream-headers.txt --output result.msgpack

V4/V4.5 的 reference_image_multiple_cached[]、director_reference_images_cached[] 支持 data 和 cache_secret_key。首次带数据，后续可以只带缓存键；缓存按本站用户隔离，失效时按官方格式返回 INVALID_CACHE_KEYS，客户端应补传素材。普通数组也支持 multipart 字段引用。不能同时发送同一数组的普通字段和 _cached 字段，详见原生接口。

MessagePack 帧格式

响应 Content-Type: application/msgpack，每一帧为：

4 字节无符号大端长度 N | N 字节 MessagePack map

event_type	字段	含义
intermediate	image 二进制、samp_ix、step_ix	中间图，通常为 JPEG
final	image 二进制、samp_ix	完整最终图；按实际文件格式解析
error	message	流内错误，不能只检查 HTTP 200
heartbeat	可忽略其他字段	保持连接

image 在这个入口中是 MessagePack 的二进制值，不是 Base64。只有上述 SSE 的图片字段使用 Data URL。网络 chunk 可能只包含半帧，也可能包含多帧，必须精确累计长度；主站当前单帧上限为 32 MiB。

收到完整 final 后即可展示或保存该图片，不需要等连接自然 EOF。尚未收到完整成品帧就遇到 EOF、截断、错误事件，不能把预览当作生成成功。

Python 示例

下载 novelai-stream.py，需要 Python 3.10+ 和 msgpack：

python -m pip install msgpack
export HAMUBOX_API_KEY='sk-your-api-key'
python novelai-stream.py novelai-native-stream.json --output result.png

此 Python 示例面向 n_samples: 1，不自动重试 POST。它先保存不含 Key 的任务 ID 文件，再解析长度帧，将最终图原样写入磁盘。请求 WebP 时使用 .webp 文件名。需要稳定结果 URL 与最终费用时，用异步客户端继续查询：

python client.py novelai --task-id task_your_existing_id

成图、元数据与恢复

未指定 parameters.image_format 时，主站流式请求默认向上游请求 PNG；显式 webp 不强制转码。已验证 V5 可直接流式返回带生成元数据的 PNG。中间 JPEG 的格式不受最终格式选项约束。

最终图片收齐并校验后，优先通过 image / final 交付；后台仍会完成存储和结算。快速交付缓存上限为每批结果 32 MiB；超限或缓存不可用时等待持久化后交付。成图中的既有元数据保留，PNG 缺失时补充；实时交付与后续转存使用相同的处理后字节。不要把提前收到图片等同于持久化成功，最终状态和实际费用以任务查询为准，流式响应 Trailer 可能没有尚未完成的结算值。

情况	恢复方式
浏览器、客户端到本站的连接断开	后台任务继续；用保存的任务 ID 查询，也可重新 GET SSE
SSE 重连时没有旧预览或成图事件	正常查询任务；实时缓存只临时保留，不保证事件历史重放，不支持 Last-Event-ID 精确续播
收到成图但任务仍在进行	可以展示和下载，同时等待同一任务的稳定链接与结算
收到成图后转存失败	显示任务错误；保留本地已收到的图片，不要自动重新生成
本站与上游之间的流在完整成图到达前中断	不保证找回成图；当前官方流式协议没有可凭本站任务 ID 再取原图的补查接口
连接已结束但没有成图	先查原任务，不能直接判定需要重发付费请求

SSE/原生流单连接最长等待 10 分钟，到时结束连接并不取消后台任务。客户端超时也不取消任务。中间图不做持久化；最终图的临时缓存不可替代文件归档。不要把 Base64 图片、API Key 或完整二进制流写进应用日志。