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.
Submit an image
POST /images
{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
"width": 832, "height": 1216 }
| Field | Type | Default | What it does |
|---|---|---|---|
prompt | string | required | The scene. English gives the most precise results. |
width, height | int | 1024 x 1024 | Pixel size. Good shapes: 1024 x 1024 (square), 832 x 1216 (portrait), 1216 x 832 (landscape). |
mode | string | generation | edit, img2img or inpaint, see below. Absent means generate from the prompt. |
image_b64 | string | Source image in base64 (PNG or JPEG), required by all three retouching modes. 12 MB decoded at most. | |
mask_b64 | string | Mask in base64: required by inpaint, optional for edit. Paint the areas to retouch in red, at the source image's size. | |
lora | string | A trained character on the account: the name returned by GET /loras. Put its trigger in the prompt. | |
lora2, lora2_strength | string, number | A second character and its strength (0 to 1, default 1) for a two-person scene. | |
steps | int | engine | Leave empty. The engine knows its own value. |
The answer:
{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }
The seed is drawn by the engine and returned for information. It cannot be fixed on input in
this version.
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.
mode | Inputs | What the engine does |
|---|---|---|
edit | image_b64 + prompt (+ optional mask_b64) | Applies the instruction to the whole image ("add sunglasses", "make it snow"). With a mask, the change concentrates inside the red area. |
inpaint | image_b64 + mask_b64 + prompt | Regenerates only the red area of the mask, following the instruction. The rest is recomposed pixel for pixel. |
img2img | image_b64 + prompt | Reworks the whole image along the prompt while keeping its composition and look: a variation. |
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\"}"
Poll
GET /images/{jobId}
| Answer | Meaning |
|---|---|
{ "status": "pending", "phase": "IN_QUEUE" } | Queued |
{ "status": "pending", "phase": "IN_PROGRESS" } | Rendering |
{ "status": "completed", "cost": 1, "file_url": "/pro/v1/images/{jobId}/file", ... } | Done, file ready |
{ "status": "failed", "detail": "..." } | Failed, and nothing is charged |
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_indisponible 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.