Pro API: generate and retouch images

One image costs 1 credit, whatever the mode. Generation from a prompt and retouching of an image you supply both go through the same route.

POST /images/quote takes the same body and answers the price without creating anything, always { "cost": 1, ... } here. It exists for symmetry with videos, where the price does vary.

Submit an image

POST /images

{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
  "width": 832, "height": 1216 }

The answer:

{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }

The seed is returned in the answer, whether you gave it or it was drawn at random: keep it to render the same image again, or a variation of it.

Asking for several at once

With count above 1, one request starts several renders, each with its own seed, and the answer lists them:

{ "count": 4, "requested": 4, "cost_total": 4,
  "jobs": [ { "jobId": "...", "seed": 178078967, "cost": 1 }, { "jobId": "...", "seed": 903412, "cost": 1 } ],
  "errors": [],
  "jobId": "...", "seed": 178078967, "cost": 1 }

Two things to read carefully.

The jobId, seed and cost of the first render are repeated at the top level. That is there so clients written before batches keep working unchanged, not because the first one matters more. Poll every entry of jobs, not just that one.

And compare count with requested. A refusal partway through, for want of credits or because the key hit its daily cap, stops the batch where it is: requested is what you asked for, count is what actually started, and errors says why it stopped. A client that assumes the two are equal quietly loses renders.

POST /images/quote takes count too, and prices the whole batch. Videos have no count: one request, one clip.

The three retouching modes

All three run on the same instruction-driven editing engine, which preserves the look of the source image. When you supply a source image, width and height are read from the image itself and do not need to be sent.

In edit, the server picks the best way to handle the edit on its own, like the app:

• with a mask: it reads the instruction and chooses between replacing what the area holds (another object, another garment, a face: the area is redrawn from what should appear there) and modifying what is there (colour, material, light). With a character lora, the area is always redrawn, face included;
• without a mask, with a character lora ("replace the woman with kara..."): the server finds the person in the photo and redraws them as the character; if it finds no one, the instruction applies to the whole image, as before.

Same price in every case (1 credit per image). The choice shows in the result, not in the response.

IMG=$(base64 -w0 photo.png)
curl -s $B/images -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{\"mode\":\"edit\",\"prompt\":\"add a red scarf, keep everything else identical\",\"image_b64\":\"$IMG\"}"

Create an image with characters, objects and a location

Add a multiref object to POST /images and the server plays your characters (Characters), your objects and animals and a location (Subjects) together in a single image, each one recognisable, like the app's "Create an image" screen. Call each one by @Name in the prompt, in English.

{ "prompt": "@Mia hands a cup of coffee to @Tom on a sunny terrace, both smiling",
  "multiref": {
    "characters": [
      { "character_id": "chr_8f3a...", "name": "Mia", "view": 1 },
      { "character_id": "chr_21bc...", "name": "Tom", "lora": "tom_v1", "strength": 1.0, "lora_pass": 0.55 }
    ],
    "subjects": [ { "subject_id": "sub_...", "name": "Mug" } ],
    "location": { "subject_id": "sub_...", "name": "Terrace" }
  },
  "width": 1344, "height": 768, "seed": 42, "count": 1 }

• At most 4 subjects (characters, objects and animals). Without a LoRA, from images only: 4 references at most, the location included. The server picks the method from the references, and places each one in the order of characters then subjects, from left to right.
• An @Name that matches no reference is refused (unknown_mention); a reference missing from the prompt is sent all the same.
• Price: one pass costs the price of one image (1 credit). A simple image is 1 pass; several characters played by a LoRA, 1 plus one pass per LoRA (4 at most); from images only, one pass per reference beyond the first; a mix, both. The total (passes x count) is reserved at submission and debited once, at the final image: a failure or a cancel costs nothing. POST /images/quote with the same body gives the exact price, the method and its passes, without starting anything.
• Answer 202: { "jobId": "mri_...", "seed", "cost", "method", "passes", "billed_passes" } (with count 2: jobs and cost_total). Polling, download and cancel use the usual routes below; while it renders, progress gives the current pass ("2/3"). An image takes 1 to 3 minutes.
• The final image stays available for 1 hour, and 10 minutes after its first download. A failed pass gives status: "failed" with reason: "render_failed"; a cancel, reason: "cancelled".
• Errors: invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size, character_not_ready, plus those of Multi-Ref (unknown_character, unknown_subject, unknown_lora, unknown_mention, multiref_too_many_references, invalid_strength...). See Limits and errors.

Poll

GET /images/{jobId}

Poll every 3 seconds, no faster: the queue is shared.

Download

GET /images/{jobId}/file

The PNG itself, as the response body (Content-Type: image/png). Available as soon as the status is completed, and 404 media_unavailable once the render is gone. Download it straight away, it is not archived.

Cancel

POST /images/{jobId}/cancel

Cancels a queued or running render. Answers { "ok": true }. Nothing is charged, and the cost reserved against the key's daily cap is given back.