Luminal Images API: Ideogram 4.5 through your Luminal key

https://images.luminal.cloud runs Ideogram 4.5's two image endpoints (and Krea 3's, see Krea 3 through the same key) under Luminal's keys and wallet. The request format is Ideogram's own: same paths, same field names, same multipart or JSON bodies, same enums, same file rules. To move an Ideogram integration here, change the host and the key. This page lists exactly what is different, so you are never surprised by a response.

Read this first if you use curl --fail-with-body … --output response.json from Ideogram's samples. A synchronous request that runs longer than 10 minutes returns HTTP 202 with the body {"generation_id": "…", "status": "pending"}. curl treats 202 as success and writes that body to response.json silently. Check the status field (or the x-luminal-status header) before you read data, and poll GET /v1/generations/{generation_id} when it says pending.

Base URL and authentication

Base URLhttps://images.luminal.cloud
Auth headerAuthorization: Bearer lum_live_… or Api-Key: lum_live_… (same key; if both are sent, Authorization wins)
Keysyour Luminal API keys from the dashboard, the same ones the Text API uses
Walletyour Luminal prepaid balance (or your contract invoice if you are a postpaid customer)

Your key is never forwarded to Ideogram. Only Content-Type, Content-Length and Accept go upstream with your request body.

Endpoints

MethodPathWhat it is
POST/v2/image/generate/ideogram-4-5Ideogram's Generate: text-to-image, or edit with up to 5 source files
POST/v2/image/precise-edit/ideogram-4-5Ideogram's Precise edit: one image plus up to 4 reference_images
GET/v1/generations/{generation_id}poll a generation (served by Luminal from its own record, see below)
GET/v1/generations?since=<ms>&limit=<n>list your recent generations (Luminal addition)
GET/v1/balanceyour available credit (Luminal addition)
GET/healthzservice liveness, no auth
GET/docs/this page

Request fields, enums, size rules, mask rules and file limits (JPEG/PNG/WebP, 50 MB per file, aspect ratio 1:6 to 6:1) are Ideogram's; see their partner kit (its early-access text still says 25 MB per file; the 50 MB Precise-edit limit is the one developer.ideogram.ai published, read 2026-10-23). Ideogram's own 400/404/413/415/422 error bodies are relayed to you unchanged. Luminal applies one per-file cap, 50 MiB (52,428,800 bytes, at or above Ideogram's Precise-edit maximum of 50 MB), to every file on both endpoints; Ideogram's lower 25 MB rule for Generate's images and mask is enforced by Ideogram itself, and its answer is relayed to you with nothing charged.

Precise edit at full resolution (context_window)

Ideogram's Precise edit (launched 2026-10-29) edits one region of an image at its original pixels and returns the whole image at its own width and height, every pixel outside the region exactly as sent. The field that drives it, context_window, passes through Luminal unchanged, as do mask and reference_images; nothing changes in how you call it here.

context_windowWhat Ideogram does
absent or noneedits the whole image; over 4,194,304 pixels (2048 × 2048) the result comes back scaled down to fit (an 8K image returns at about 2720 × 1530)
autoneeds a mask; fits the edit region around the masked pixels, so the result keeps the image's full resolution
y_min,x_min,y_max,x_maxyou name the region by its corner pixels, rows first; each side at least 256 px, area at most 4,194,304 px, aspect ratio within 6:1, entirely inside the image; a mask may narrow the edit inside it

The price is the tier's, whatever the image size (verified 2026-10-29 through this host: an 8K edit with auto and with an explicit window both returned 7680 × 4320 with 100 % of the pixels outside the window byte-identical to the source, billed medium $0.0600). Ideogram's validation errors for a bad window (auto without a mask, a window outside the image) are relayed as its 400, nothing charged. Full-resolution results are large: an 8K edit returns a PNG of about 45 MB, which counts toward the 10-minute synchronous wait only through its generation time, not its download.

What is different from calling Ideogram directly

1. Two Ideogram features are refused

FieldResponse
webhook_url400 invalid_request_error / webhook_not_supported. Poll GET /v1/generations/{generation_id} instead.
image_asset_identifiers, image_asset_identifier, reference_image_asset_identifiers, mask_asset_identifier, and any field ending in _asset_identifier or _asset_identifiers400 invalid_request_error / asset_identifiers_not_supported. Upload the image files instead.

Both are refused in multipart and JSON form. Ideogram's kit samples that use them return 400 here.

2. Requests that cannot be priced are refused (400 ambiguous_request)

Ideogram's response never says which quality tier ran or how many images were requested, and you are billed by tier and count, so the request must state them unambiguously. These return 400 invalid_request_error with code ambiguous_request (the message says which rule):

A multipart body over 256 MiB is refused with 413 before it is read (Ideogram's own maximum is 250 MB for a Precise edit, 1 image plus 4 references at 50 MB, and 125 MB for Generate, 5 files at 25 MB). An application/json body carries no files, so it is capped at 1 MiB.

3. async, waiting, and the 10-minute limit

Luminal always runs your generation asynchronously at Ideogram and polls it for you. Your async field decides only what you get back:

4. Polling is served by Luminal, never relayed

GET /v1/generations/{generation_id} with your key returns Luminal's record of the generation:

StateResponse
still running200 {"generation_id": "…", "status": "pending"} + Retry-After: 2 + x-luminal-status: pending
completedIdeogram's completed body, stored when the generation finished, with the charge headers
failedthe failure body Ideogram returned, with the HTTP status Ideogram's poll gave it (also inside the body as upstream_status; a status: failed body Ideogram returned with 200 is served as 200), x-luminal-status: failed. The same status is returned whether you read the failure on the synchronous response or here. A refusal of Luminal's partner credentials by Ideogram is never relayed as your 401/402/403: it is 502 upstream_auth or 503 at_capacity, and the generation itself keeps being polled
not yours, or unknown404

Polls do not count against your request limit; they have their own budget of 600 per minute. Polling faster than Retry-After never makes a generation finish sooner: Luminal polls Ideogram on its own schedule (every second for the first ten seconds, then every two, then every five) regardless of how often you ask. Records are kept for 30 days.

5. Finding a generation whose response you lost

GET /v1/generations?since=<unix ms>&limit=<n ≤ 100> returns your generations newest-first:

[{"request_id": "…", "generation_id": "…", "status": "settled", "created_at_ms": 1790000000000,
  "model": "ideogram-4-5", "quality": "high", "pricing_mode": "text_to_image", "num_images": 2,
  "charged_units": 2000000000}]

status is one of submitting, pending, settled (completed and charged), failed, unknown_outcome, timed_out; model is the model that was called (ideogram-4-5, or krea-3 on Krea 3 jobs); pricing_mode is text_to_image or edit (null on Krea 3 jobs and on records from before 2026-10-23). Use it after a dropped connection to find and poll the generation you were charged for.

6. Luminal headers on every response

HeaderMeaning
x-luminal-request-idLuminal's id for this request; quote it in support requests
x-luminal-generation-idIdeogram's generation_id or Krea's job_id, once known
x-luminal-qualitythe tier you were billed at (very_low / low / medium / high; Krea 3: 1k / 2k)
x-luminal-pricing-modeIdeogram only: the price column you were billed under, text_to_image (Generate with no source images) or edit (Precise edit, or Generate with source images); absent on Krea 3 responses and on records from before 2026-10-23
x-luminal-billed-imagesimages billed (charge) or images held for (hold)
x-luminal-cost-usddollars, 4 decimals
x-luminal-cost-kindhold on a submit response or a 202; charge on a completed body
x-luminal-statuscompleted, pending or failed
x-luminal-upstream-request-idIdeogram's request id, when they send one

From Ideogram's response only Content-Type, Content-Length / Content-Encoding and Retry-After are relayed. Ideogram's rate-limit headers describe Luminal's partner quota, not your account, and are not relayed.

Billing

Prices (list, US dollars per image)

TierText-to-image (Generate, no source images)Edit (Precise edit, or Generate with source images)Notes
very_lownot available$0.0080a source image is required
low$0.0300$0.0300
medium$0.0600$0.0600default with source images and for Precise edit
high$0.1000$0.2200default for text-to-image; best-of-candidates, slowest

These prices are pass-through: they are exactly what Ideogram charges, tier for tier and mode for mode, so they follow Ideogram's own price card (matched to it on 2026-10-23) and change when it does. x-luminal-pricing-mode on every Ideogram response names the column you were billed under. num_images counts returned outputs, not the candidates a best-of tier renders internally. Contract customers may have their own price card; x-luminal-cost-usd always shows what you paid.

Balance

GET /v1/balance returns

{"client_id": "…", "available_units": 1234500000000, "units_per_usd": "10000000000", "postpaid": false}

available_units / 10^10 is dollars (the example is $123.45). available_units already excludes holds for generations in flight. For invoiced (postpaid: true) accounts the number is informational: requests are never refused for credit.

Limits

LimitDefaultWhen exceeded
requests per minute (both POST endpoints together)60429 x-reject-reason: client-request-rate-limit
images per minute (sum of num_images)120429 x-reject-reason: client-image-rate-limit
generations in flight at once8429 x-reject-reason: client-inflight-limit
polls per minute (GET /v1/generations/{id})600429 x-reject-reason: client-poll-rate-limit
failed authentications per source IP per minute10429 x-reject-reason: ip-auth-failure-rate-limit
request body256 MiB (multipart); 1 MiB (application/json)413

Every 429 and 503 carries Retry-After (seconds); every 429 and every 503 at_capacity also carries x-reject-reason naming the limit. Wait that long and retry the same request. Higher limits are set per account: ask.

Errors

Luminal's own errors use one JSON shape:

{"error": {"code": "insufficient_credits", "message": "out of credits", "type": "billing_error"}}
StatuscodetypeMeaningWhat to do
401(empty body)unknown or inactive key, or no keycheck the header and the key
402insufficient_creditsbilling_erroryour prepaid balance cannot cover num_images × pricetop up in the dashboard, or send fewer images
402no_billing_accountbilling_errorthe key has no wallet yetcontact support
403model_not_allowedpermission_errorthis key is not enabled for image generation (key scope, or a contract account not yet enabled)ask to have it enabled
403account_restrictedpermission_errorthe account is suspendedcontact support
403not_a_customer_keypermission_errorthe key is not a customer keyuse a customer API key
400webhook_not_supportedinvalid_request_errorwebhook_url was sentremove it, poll instead
400asset_identifiers_not_supportedinvalid_request_erroran asset-identifier field was sentupload files instead
400ambiguous_requestinvalid_request_errorsee section 2; message names the rulefix the field
400invalid_requestinvalid_request_errormalformed multipart or JSONfix the body
400 / 404 / 413 / 415 / 422(Ideogram's body, verbatim)Ideogram rejected the request (422 = prompt safety; 413 = a file over Ideogram's own per-endpoint limit, e.g. a Generate file over its 25 MB rule)read Ideogram's message; nothing was charged
404not_foundinvalid_request_errorunknown route, or a generation that is not yourscheck the id
413payload_too_largeinvalid_request_errorbody over 256 MiB (multipart) or 1 MiB (JSON); an oversized multipart body is refused at the edge, before the upload completes. A 413 in any other shape is Ideogram's own (a Generate file over its 25 MB rule), relayed verbatim, nothing chargedreduce the upload
415unsupported_media_typeinvalid_request_errorContent-Type is neither multipart/form-data nor application/jsonset it
429rate_limit_exceededrate_limit_errorone of your limits, or (x-reject-reason: upstream-rate-limit) Ideogram rate-limited Luminalwait Retry-After, retry; nothing was charged
502upstream_error / upstream_auth / upstream_malformedupstream_errorIdeogram returned a server error or an unreadable responseretry later; nothing was charged
503at_capacityserver_errorLuminal's partner capacity or Ideogram's account is momentarily exhausted, or Ideogram is pausing after repeated errorswait Retry-After (up to 60 s), retry; nothing was charged
503server_errorserver_errora transient storage conflict on Luminal's sidewait Retry-After (1 s), retry; nothing was charged
504upstream_timeoutupstream_errorIdeogram did not answer the submit in time, so the outcome is unknown; the hold was released; error.request_id names the recorddo not assume it failed silently later: no output will be delivered for it; submit again if you need the image

402 versus 503. A 402 is about your wallet and will not clear until you top up. A 503 is on Luminal's or Ideogram's side, clears by itself, and never charges you; retry after Retry-After.

Never retry a POST blindly after a client-side timeout. Set your client timeout above 10 minutes for synchronous calls (or use async=true), and after any dropped connection use GET /v1/generations?since= to see whether the generation exists before you submit it again.

Outputs, copies and retention

Krea 3 through the same key

The same host and key also run Krea 3 (Krea's instruction-following image model, text-to-image and editing on one endpoint). The request format is Krea's own: same path, same JSON fields, same enums. Four routes, registered only while Luminal has a Krea key:

MethodPathWhat it is
POST/generate/image/krea/krea-3Krea 3: text-to-image, or edit with up to 8 references in image_urls
POST/assetsupload a reference image (JPEG/PNG/WebP, 75 MB); returns Krea's image_url to pass in image_urls
GET/jobs/{job_id}poll a job (served by Luminal from its own record, like /v1/generations/{id})
DELETE/jobs/{job_id}cancel a running job

Scope: a key whose allowed_models is restricted must name krea-3 (ideogram-4-5 does not open it, nor the reverse). Everything else — wallet, headers, limits, error shapes — is as above, with these Krea-specific rules:

Always asynchronous

Krea itself only works asynchronously. POST /generate/image/krea/krea-3 returns Krea's job object ({"job_id": "…", "status": "queued", …}, HTTP 200) as soon as Krea accepts it, with x-luminal-cost-kind: hold; poll GET /jobs/{job_id}:

StateResponse
still running200 {"job_id": "…", "status": "processing"} + Retry-After: 2 + x-luminal-status: pending
completedKrea's completed job body (result.urls[0] is the image), with the charge headers
failed or cancelledKrea's job body with its error, 200 (as Krea's own /jobs/{id} answers), x-luminal-status: failed, nothing charged
not yours, unknown, or an Ideogram id404

There is no synchronous wait and no webhook: an X-Webhook-URL request header is refused with 400 webhook_not_supported; X-Api-Zero-Data-Retention is not offered through Luminal (400).

The request must be priceable

Krea bills per generation by the output size, by every reference image's size, and by the thinking mode, and its response never says what it charged — so Luminal works the price out from the request before the hold. Every field Krea documents is accepted: prompt, image_urls, thinking_mode, priority, resolution, aspect_ratio, width/height, seed, negative_prompt, regions and regional_edit. The body is relayed to Krea exactly as you sent it.

400 ambiguous_request (or invalid_request) when:

Region edits (bounding boxes)

To change only part of an image, mark boxes on your references in regions and set regional_edit: true: Krea changes what the boxes and prompt ask for and keeps the rest of the image exact. Boxes on the first image (image_idx: 0) mark where edits happen; boxes on other images mark source objects to draw from. Refer to a box as @label, or @1, @2, … by position, in the prompt or in another box's note. A box's note takes precedence over the prompt inside that box, and with at least one non-blank note prompt may be left out.

Each box is checked before the hold (400 invalid_request otherwise): x, y from 0 to 1 and width, height above 0 and at most 1 (fractions of the image, from its top-left corner), with the box inside the image (x + width and y + height at most 1); an integer image_idx naming one of your image_urls; optional label (1–128 characters) and note (up to 600); nothing else. At most 24 boxes. regional_edit: true needs at least one image. Regions cost nothing extra: the price is the same as the same edit without boxes.

References: upload them through /assets

Each reference is priced by its size, so Luminal measures every reference before the hold and never fetches a URL you supply. Two forms are accepted in image_urls:

POST /assets takes multipart/form-data with one file part (JPEG, PNG or WebP whose size can be read from the header; Krea's other formats are not accepted here) and an optional description, forwards it to Krea unchanged, and relays Krea's answer ({"id", "image_url", "width", "height", …}). Uploads are free and count against your requests-per-minute limit only. Records are kept for 30 days; re-upload after that.

A reference whose longest side is 1536 px or less is priced as a 1K reference, anything larger as 2K. Krea has not published its own boundary; if it turns out to differ, Luminal's rule (not Krea's) is what you were billed by.

Prices (list, US dollars per generation; one image per job)

Component1K output2K output
base$0.0300$0.0600
each 1K reference image+$0.0200+$0.0200
each 2K reference image+$0.0700+$0.0700
thinking_mode: high+$0.0200+$0.0200
thinking_mode: ultra (with references)not available+$0.2000

The sum is the hold (x-luminal-cost-usd), and the charge when the job completes with an image. x-luminal-quality is 1k or 2k; x-luminal-billed-images is 1; there is no pricing mode (x-luminal-pricing-mode is absent). A job that completes with no output, fails, or is cancelled charges nothing. Contract price cards may override the base price per resolution; the surcharges are the same for everyone.

Cancelling

DELETE /jobs/{job_id} forwards one cancel to Krea and relays its answer (Krea only cancels jobs that are still queued or processing). The response still shows the hold: the refund happens when Luminal's next poll sees the job cancelled, a few seconds later. A job that is already finished answers 200 {"job_id", "status": "completed"|"failed"} without calling Krea.

Capacity

Krea limits how many jobs Luminal's key may run at once. When that ceiling is hit the submit returns 503 at_capacity with x-reject-reason: upstream-concurrency-limit and a Retry-After (Krea's, else 5 s); nothing is charged, and the ceiling clears as jobs finish — retry after the delay. Your own per-key limits (requests, images, in-flight generations) are shared between Ideogram and Krea.

Example

# 1. upload a reference (once; keep the image_url)
curl --fail-with-body https://images.luminal.cloud/assets \
  -H "Authorization: Bearer $LUMINAL_API_KEY" -F "file=@product.png" --output asset.json
REF=$(jq -r .image_url asset.json)

# 2. submit (2K output + one reference + high thinking = $0.06 + $0.02 or $0.07 + $0.02)
curl --fail-with-body https://images.luminal.cloud/generate/image/krea/krea-3 \
  -H "Authorization: Bearer $LUMINAL_API_KEY" -H "Content-Type: application/json" \
  -d "{\"prompt\": \"Place the product on a clean studio background\", \"resolution\": \"2k\", \"thinking_mode\": \"high\", \"image_urls\": [\"$REF\"]}" \
  --output job.json
JOB=$(jq -r .job_id job.json)

# 3. poll until status is completed; result.urls[0] is the image
curl -s -H "Authorization: Bearer $LUMINAL_API_KEY" https://images.luminal.cloud/jobs/$JOB

A region edit on the same uploaded image (1K output + one reference; boxes are free):

curl --fail-with-body https://images.luminal.cloud/generate/image/krea/krea-3 \
  -H "Authorization: Bearer $LUMINAL_API_KEY" -H "Content-Type: application/json" \
  -d @- --output job.json <<EOF
{
  "prompt": "Replace @label with a matte black label reading NOIR; keep everything else exact",
  "image_urls": ["$REF"],
  "regions": [{"image_idx": 0, "x": 0.38, "y": 0.42, "width": 0.24, "height": 0.18, "label": "label"}],
  "regional_edit": true,
  "resolution": "1k"
}
EOF

Examples

Synchronous text-to-image (bills at high, the Ideogram default, unless you set quality):

curl --fail-with-body https://images.luminal.cloud/v2/image/generate/ideogram-4-5 \
  -H "Authorization: Bearer $LUMINAL_API_KEY" \
  --form-string 'prompt=A small ceramic teapot on a wooden table, soft morning light' \
  -F "quality=medium" -F "num_images=1" \
  --output response.json
# check: jq -r '.status // "completed"' response.json   (a 202 body says "pending")

Asynchronous edit, then poll:

curl --fail-with-body https://images.luminal.cloud/v2/image/generate/ideogram-4-5 \
  -H "Api-Key: $LUMINAL_API_KEY" \
  -F "images=@scene.png" -F "size=source" -F "quality=low" -F "async=true" \
  --form-string 'prompt=Make the sky overcast. Keep everything else unchanged.' \
  --output submit.json
GEN=$(jq -r .generation_id submit.json)
curl -s -H "Api-Key: $LUMINAL_API_KEY" https://images.luminal.cloud/v1/generations/$GEN

JSON text-to-image with a boolean async:

curl --fail-with-body https://images.luminal.cloud/v2/image/generate/ideogram-4-5 \
  -H "Authorization: Bearer $LUMINAL_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "A lighthouse at dusk, watercolor", "quality": "low", "num_images": 2, "async": true}'

Questions or higher limits: support@luminalai.com, quoting x-luminal-request-id.

Output URLs

Ideogram serves outputs from https://ideogram.ai/api/images/ephemeral/… and does not state how long they stay valid. Download what you need as soon as the response arrives. Luminal keeps a copy of every delivered image for 7 days (support and dispute evidence only; there is no customer route to those copies yet).