DEV Community

Ilan Kim
Ilan Kim

Posted on

Calling the NovelAI V5 API directly: nai-diffusion-5-full request body, params_version 4/3/1/0 identical, missing v4_prompt is a 500

#novelai #api #node #javascript

nai-diffusion-5-full takes the same body skeleton V4 took, posted to https://image.novelai.net/ai/generate-image, and params_version — the one field every third-party tool fills in differently — returns a pixel-for-pixel identical image whether you send 4, 3, 1, or 0 with this body skeleton. JSON and multipart bodies gave the same result too. What does break it: drop either v4_prompt or v4_negative_prompt and you get 500 Internal Server Error rather than a 400, set Content-Type by hand on a FormData body and you get a missing multipart boundary 400, and post to the old host and you get a model must be a valid enum value 400.

This is for people calling NovelAI V5 from their own scripts rather than through a ComfyUI node or a GUI like NAIA (a community-built desktop front end for NovelAI). On 2026-09-14, on macOS 26.5.2 with Node v22.22.3 and an Opus account (tier: 3), I generated six images inside the free band and compared request formats, error responses, and balance changes; I also read the strings out of the official web client bundle the same day. Two terms if NovelAI is new to you: Anlas is NovelAI's generation credit, and Opus is the top subscription tier, which generates one image at a time at the common sizes and up to 28 steps without spending any, as long as no base image is involved and the allowance has not run out. The policy and the per-size cost table are in the earlier post, the measurements through a ComfyUI node are in the one after it, and this post covers only the request contract.

The problem

If you look at third-party tools' request bodies to work out how to call V5 yourself, the params_version value is different in every one of them. ComfyUI_NAIDGenerator, a ComfyUI node for NovelAI, sends 1. The README of ComfyUI_RS_NAI_API_Request, another ComfyUI node, says "V5 requests use params_version: 4 while older models keep params_version: 3". The changelog of NAIWeaver, a standalone NovelAI client, says "send params_version: 4" (all checked 2026-09-14). The official OpenAPI document has no required array and no nai-diffusion-5 string, so it cannot settle which one is right.

From there, nudging the body around gets you three responses. All three are verbatim from this round of testing:

POST https://api.novelai.net/ai/generate-image  (old host)
400 {"statusCode":400,"message":"model must be a valid enum value"}

POST https://image.novelai.net/ai/generate-image  (v4_prompt or v4_negative_prompt omitted)
500 {"statusCode":500,"message":"Internal Server Error"}

POST https://image.novelai.net/ai/generate-image  (FormData + Content-Type: multipart/form-data set by hand)
400 {"statusCode":400,"message":"missing multipart boundary"}
Enter fullscreen mode Exit fullscreen mode

The first one has different wording from the "update to the image URL" 400 the balance lookup returns. The old host accepts the generation request itself but does not know the V5 model ID, so from the message alone it looks like you typed the model ID wrong.

The second is the confusing one. It is a 500 rather than a 400-class validation error, so it reads like a server outage, but the cause is your request body. The third one appears when you hand Node's fetch a FormData body and set the header yourself, because the boundary undici would have attached automatically disappears.

What the measurements show

params_version does not change the result with this body skeleton. Same prompt, seed 1234567890, 832×1216, 28 steps, one image per value:

params_version Response Response time PNG Source Anlas
4 (official web client) 200 2.5 s NovelAI Diffusion V5 0ADF9AB7 9,930 → 9,930
3 (the value said to be for older models) 200 1.8 s same no change
1 (ComfyUI_NAIDGenerator) 200 1.9 s same no change
0 (a value no tool uses) 200 1.8 s same no change

Comparing the four images pixel by pixel with Pillow gives a mean absolute difference of 0 and 0% of pixels changed, so they are completely identical. The Comment metadata of the returned PNGs has no params_version field either. If the value were read and acted on, 0 should at least have been rejected, so with this skeleton it has to be treated as ignored. Whether that also holds for other field combinations — character prompts, inpainting and so on — I did not check.

A contact sheet placing the four images received with params_version 4, 3, 1, and 0 side by side; all four are identical down to the pixel

So where does 4 come from? In the novelai.net bundle I pulled on 2026-09-14 (_app-b7172cc1a6a0b340.js), the default parameters in the nai-diffusion-5-full branch start with params_version:4, and there is migration code that raises stored settings to 4 if params_version<4. The string v5_prompt appears 0 times; v4_prompt appears twice.

The transport format makes no difference to the result either. Sending the params_version: 1 body as JSON and sending it as a JSON blob in the request part of a FormData both returned 200 with identical pixels. The debug toggle text in that same bundle describes the default as "Image generation requests will be sent as multipart form data." and the checked state as "JSON (pre-multipart-form format)", so multipart is the official client's default and JSON survives as the legacy format.

Transport Content-Type handling Response
JSON application/json set explicitly 200, 917,294-byte zip
multipart header not set (automatic boundary) 200, pixels identical to JSON
multipart multipart/form-data set by hand 400 missing multipart boundary

You cannot leave out v4_prompt or v4_negative_prompt. With everything else left alone, a body with both keys removed, a body with only v4_prompt removed, and a body with only v4_negative_prompt removed all came back with the same 500, and none of them moved the balance. Together with the absence of v5_prompt in the bundle, I take this to mean V5 still requires the V4 structure as it is.

Authentication errors all arrive lumped into a single 401. Leave the Authorization header out entirely, or put a space inside the token value, and the response is the same 401 {"statusCode":401,"message":"Unauthorized"} either way. Since the response cannot tell you whether the token string is mangled or the header is missing, don't print the value: check its length and whether it is unchanged by trim().

For the free band, this adds the landscape size to the table in the earlier post. 1216×832 (pixel product 1,011,712) at 28 steps, one image, was also 0 Anlas, and across six generations usage.percent did not move from 87. The battery reading is an integer, which means per-image consumption below 1% is invisible in it.

A V5 Full sample received at the 1216×832 landscape size; one image at 28 steps, so 0 Anlas

I did not find an API that quotes the price up front this time. POST /ai/generate-image/request-price, which appears in the web bundle, returned 404 page not found on image.novelai.net and 404 Cannot POST /ai/generate-image/request-price on api.novelai.net. The web UI does show an estimated Anlas cost on the generate button, but I could not get the same number out of this path, and whether another path exists I could not confirm.

What to do

  1. Use one host, https://image.novelai.net. Generation (/ai/generate-image) and balance lookup (/user/subscription) are both on it, while api.novelai.net rejects generation with model must be a valid enum value and lookups with "update to the image URL".
  2. Use the body below as it stands. This JSON is the full body that returned 200 in the params_version: 4 row of the table above, and the prompt goes in the same string in three places: top-level input, parameters.prompt, and v4_prompt.caption.base_caption. Use 4 for params_version to match the official web client, but don't read any meaning into the value: 
{
  "input": "1girl, solo, silver hair, school uniform, looking at viewer, upper body, simple background, masterpiece, best quality",
  "model": "nai-diffusion-5-full",
  "action": "generate",
  "parameters": {
    "params_version": 4,
    "width": 832, "height": 1216, "scale": 5, "sampler": "k_euler_ancestral", "steps": 28,
    "seed": 1234567890, "n_samples": 1, "ucPreset": 3, "qualityToggle": false,
    "sm": false, "sm_dyn": false, "dynamic_thresholding": false, "controlnet_strength": 1,
    "legacy": false, "add_original_image": false, "cfg_rescale": 0, "noise_schedule": "karras",
    "legacy_v3_extend": false, "uncond_scale": 1, "negative_prompt": "",
    "prompt": "1girl, solo, silver hair, school uniform, looking at viewer, upper body, simple background, masterpiece, best quality",
    "reference_image_multiple": [], "reference_information_extracted_multiple": [], "reference_strength_multiple": [],
    "extra_noise_seed": 1234567890,
    "v4_prompt": { "use_coords": false, "use_order": false, "caption": { "base_caption": "1girl, solo, silver hair, school uniform, looking at viewer, upper body, simple background, masterpiece, best quality", "char_captions": [] } },
    "v4_negative_prompt": { "use_coords": false, "use_order": false, "caption": { "base_caption": "", "char_captions": [] } }
  }
}
Enter fullscreen mode Exit fullscreen mode

Save that JSON as body.json, put the file below in the same folder, and it runs as is. The key file is a text file with a pst- token on the line after a line labeled "novelai", and the token stays in memory only. Running it with node nai-v5-direct.mjs <key file> got me a 200 and an image_0.png whose pixels match the table above:

// node nai-v5-direct.mjs <key file> — the key file has a pst- token on the line after the "novelai" label
import { readFile, writeFile } from 'node:fs/promises';

const lines = (await readFile(process.argv[2], 'utf8')).split(/\r?\n/).map((l) => l.trim());
const token = lines[lines.findIndex((l) => /novelai/i.test(l)) + 1];
const body = JSON.parse(await readFile('body.json', 'utf8'));

const r = await fetch('https://image.novelai.net/ai/generate-image', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify(body),
});
console.log(r.status, r.headers.get('content-type'));
if (r.ok) await writeFile('out.zip', Buffer.from(await r.arrayBuffer())); // image_0.png is inside
else console.log(await r.text());
Enter fullscreen mode Exit fullscreen mode
  1. For transport, set Content-Type: application/json explicitly if you send JSON, and do not set a Content-Type header yourself if you use FormData. Node 22's fetch builds the header with the boundary on its own for a FormData body.
  2. The response is a binary/octet-stream zip with image_0.png inside. Check the model from the Source value in the PNG's tEXt chunk (NovelAI Diffusion V5 0ADF9AB7).
  3. To stay at 0 Anlas, keep all of it: Opus, one image (n_samples: 1), no base image, a pixel product of 1,048,576 or less, and 28 steps or fewer — then read /user/subscription before and after the generation and compare the sum trainingStepsLeft.fixedTrainingStepsLeft + trainingStepsLeft.purchasedTrainingSteps. trainingStepsLeft is an object rather than an integer, so you cannot subtract it directly. usage.percent is too coarse to use for per-image checks.
  4. Respect the API document's "all generation requests must be initiated by a human action" and its 429 note ("API clients should not attempt to retry") by sending human-initiated requests one at a time with a gap between them. This round of measurements ran with 6 seconds between requests and a concurrency of 1.

Image: the sample outputs in this post are AI images generated with NovelAI Diffusion V5.

Takeaways

With this body skeleton, params_version is ignored — 4, 3, 1, and 0 all return the same pixels — and JSON and multipart bodies produced the same image. The parts that actually matter are the host, image.novelai.net, and keeping both v4_prompt and v4_negative_prompt in the body, since dropping either one returns a 500 rather than a validation 400.

Unverified

  • How a 429 behaves: the API document explicitly forbids retrying, so I didn't provoke one on purpose. 429 isn't even documented for the image endpoints, so I don't know the actual message.
  • What happens when director_reference_* fields are sent to V5: V5 doesn't support Precise Reference, but the schema doesn't block these fields. Whether that is a 400 or "ignored and billed", I didn't run, because of the billing risk.
  • The actual charge for a 29-step or 2-image request: that is the paid band, so I didn't generate it. The price lookup path I tried was a 404, so the only figure I have is the 45 Anlas for the large size from the earlier post.
  • The absolute capacity of the Opus battery (allowance): usage.percent stayed fixed at 87 across six images, so I couldn't work backwards to a per-image draw.
  • How params_version behaves with other body skeletons: I didn't run it with character-prompt, inpainting, or img2img bodies. Large values such as 9 also fell outside the generation budget.

Changelog

Version Description
1.0 2026-09-14 first version (macOS 26.5.2 · Node v22.22.3 · Opus, 6 free-tier generations)

Top comments (0)