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.jsonfrom 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 toresponse.jsonsilently. Check thestatusfield (or thex-luminal-statusheader) before you readdata, and pollGET /v1/generations/{generation_id}when it sayspending.
Base URL and authentication
| Base URL | https://images.luminal.cloud |
| Auth header | Authorization: Bearer lum_live_… or Api-Key: lum_live_… (same key; if both are sent, Authorization wins) |
| Keys | your Luminal API keys from the dashboard, the same ones the Text API uses |
| Wallet | your 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
| Method | Path | What it is |
|---|---|---|
POST | /v2/image/generate/ideogram-4-5 | Ideogram's Generate: text-to-image, or edit with up to 5 source files |
POST | /v2/image/precise-edit/ideogram-4-5 | Ideogram'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/balance | your available credit (Luminal addition) |
GET | /healthz | service 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_window | What Ideogram does |
|---|---|
absent or none | edits 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) |
auto | needs 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_max | you 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
| Field | Response |
|---|---|
webhook_url | 400 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_identifiers | 400 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):
qualityornum_imagesorasyncgiven more than once (repeated multipart parts, or a JSON key twice);num_imagesthat is not exactly one of1…8after trimming: no08,4.0,"2"as a JSON string;qualitythat is not exactlyvery_low,low,mediumorhigh(case-sensitive), or a tier Ideogram does not allow for that request (very_lowon text-to-image);- a file part that is empty, or that is not a JPEG, PNG or WebP;
- more source files than Ideogram allows (Generate: 5, or 4 with a mask; Precise edit: 1 image plus 4 references, or 3 with a mask);
- a missing or blank
prompt, or one over 10,000 characters; a file part over 50 MiB (52,428,800 bytes; themessagequotes that number); seedoutside 0 … 2147483647, or an emptyseed.
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:
asyncabsent orfalse(synchronous): the response is Ideogram's completed body (generation_id,seed,data[]) once the generation finishes, exactly as a direct sync call would return, plus the Luminal headers below. If it has not finished after 10 minutes (or, rarely, if it finished but Luminal's own record of it is still being written), you get202{"generation_id", "status": "pending"}withRetry-After: 5andx-luminal-status: pending. The generation keeps running; poll for it. See the note at the top.async=true(multipart texttrue, JSON booleantrue): you get Ideogram's submit response right away, relayed as is, plus the Luminal headers; poll for the result.
4. Polling is served by Luminal, never relayed
GET /v1/generations/{generation_id} with your key returns Luminal's record of the generation:
| State | Response |
|---|---|
| still running | 200 {"generation_id": "…", "status": "pending"} + Retry-After: 2 + x-luminal-status: pending |
| completed | Ideogram's completed body, stored when the generation finished, with the charge headers |
| failed | the 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 unknown | 404 |
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
| Header | Meaning |
|---|---|
x-luminal-request-id | Luminal's id for this request; quote it in support requests |
x-luminal-generation-id | Ideogram's generation_id or Krea's job_id, once known |
x-luminal-quality | the tier you were billed at (very_low / low / medium / high; Krea 3: 1k / 2k) |
x-luminal-pricing-mode | Ideogram 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-images | images billed (charge) or images held for (hold) |
x-luminal-cost-usd | dollars, 4 decimals |
x-luminal-cost-kind | hold on a submit response or a 202; charge on a completed body |
x-luminal-status | completed, pending or failed |
x-luminal-upstream-request-id | Ideogram'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
- Unit: one image. The price depends on the quality tier and on the request mode: text-to-image (Generate with no source images) or edit (Precise edit, or Generate with one or more source images). It does not depend on image size. (Krea 3 is priced per job, below.)
- Tier: your explicit
quality; otherwise Ideogram's default, which is **highfor text-to-image** (Generate without source files) andmediumfor every edit. Text-to-image withoutqualitytherefore bills at the most expensive tier, exactly as Ideogram runs it. - Hold: when a request is accepted,
num_images × price(for your tier and mode) is reserved from your balance (x-luminal-cost-kind: hold). Your dashboard balance dips by the hold while the generation runs. - Charge: when it completes you are charged for delivered images only: entries in
data[]withis_image_safe: trueand a non-emptyurl. Flagged or missing outputs are not charged. The charge is never more than the hold; the difference is released. - Refund: if Ideogram rejects or fails the request, or Luminal cannot determine the outcome, the whole hold is released. Nothing is charged for a 4xx or 5xx response.
Prices (list, US dollars per image)
| Tier | Text-to-image (Generate, no source images) | Edit (Precise edit, or Generate with source images) | Notes |
|---|---|---|---|
very_low | not available | $0.0080 | a source image is required |
low | $0.0300 | $0.0300 | |
medium | $0.0600 | $0.0600 | default with source images and for Precise edit |
high | $0.1000 | $0.2200 | default 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
| Limit | Default | When exceeded |
|---|---|---|
requests per minute (both POST endpoints together) | 60 | 429 x-reject-reason: client-request-rate-limit |
images per minute (sum of num_images) | 120 | 429 x-reject-reason: client-image-rate-limit |
| generations in flight at once | 8 | 429 x-reject-reason: client-inflight-limit |
polls per minute (GET /v1/generations/{id}) | 600 | 429 x-reject-reason: client-poll-rate-limit |
| failed authentications per source IP per minute | 10 | 429 x-reject-reason: ip-auth-failure-rate-limit |
| request body | 256 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"}}
| Status | code | type | Meaning | What to do |
|---|---|---|---|---|
| 401 | (empty body) | unknown or inactive key, or no key | check the header and the key | |
| 402 | insufficient_credits | billing_error | your prepaid balance cannot cover num_images × price | top up in the dashboard, or send fewer images |
| 402 | no_billing_account | billing_error | the key has no wallet yet | contact support |
| 403 | model_not_allowed | permission_error | this key is not enabled for image generation (key scope, or a contract account not yet enabled) | ask to have it enabled |
| 403 | account_restricted | permission_error | the account is suspended | contact support |
| 403 | not_a_customer_key | permission_error | the key is not a customer key | use a customer API key |
| 400 | webhook_not_supported | invalid_request_error | webhook_url was sent | remove it, poll instead |
| 400 | asset_identifiers_not_supported | invalid_request_error | an asset-identifier field was sent | upload files instead |
| 400 | ambiguous_request | invalid_request_error | see section 2; message names the rule | fix the field |
| 400 | invalid_request | invalid_request_error | malformed multipart or JSON | fix 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 | |
| 404 | not_found | invalid_request_error | unknown route, or a generation that is not yours | check the id |
| 413 | payload_too_large | invalid_request_error | body 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 charged | reduce the upload |
| 415 | unsupported_media_type | invalid_request_error | Content-Type is neither multipart/form-data nor application/json | set it |
| 429 | rate_limit_exceeded | rate_limit_error | one of your limits, or (x-reject-reason: upstream-rate-limit) Ideogram rate-limited Luminal | wait Retry-After, retry; nothing was charged |
| 502 | upstream_error / upstream_auth / upstream_malformed | upstream_error | Ideogram returned a server error or an unreadable response | retry later; nothing was charged |
| 503 | at_capacity | server_error | Luminal's partner capacity or Ideogram's account is momentarily exhausted, or Ideogram is pausing after repeated errors | wait Retry-After (up to 60 s), retry; nothing was charged |
| 503 | server_error | server_error | a transient storage conflict on Luminal's side | wait Retry-After (1 s), retry; nothing was charged |
| 504 | upstream_timeout | upstream_error | Ideogram did not answer the submit in time, so the outcome is unknown; the hold was released; error.request_id names the record | do 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
data[].urlare Ideogram's own URLs, returned unchanged. Their lifetime is Ideogram's; download outputs promptly.- Luminal keeps a copy of every delivered image for 7 days (support evidence, and a safety net if an Ideogram URL expires early). Ask support with your
x-luminal-request-idif you need one. The copy is best effort and never affects your response or your charge; an output over 64 MiB (possible for a full-resolution Precise edit of a very large photo) is returned and billed as usual but not kept. - The generation record (your
request_id,generation_id, tier, pricing mode, counts, charge, the first 2 KB of the prompt and Ideogram's completed body) is kept for 30 days, and is whatGET /v1/generations/{generation_id}serves.
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:
| Method | Path | What it is |
|---|---|---|
POST | /generate/image/krea/krea-3 | Krea 3: text-to-image, or edit with up to 8 references in image_urls |
POST | /assets | upload 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}:
| State | Response |
|---|---|
| still running | 200 {"job_id": "…", "status": "processing"} + Retry-After: 2 + x-luminal-status: pending |
| completed | Krea's completed job body (result.urls[0] is the image), with the charge headers |
| failed or cancelled | Krea'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 id | 404 |
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.
- Output size.
resolutionis1kor2k(either case; relayed as you sent it), and is required unless you sendwidth/height(Krea's docs mention a 1K default, but Krea refuses a request with neither). Instead ofresolution/aspect_ratioyou may sendwidthandheight(both, 1–4096): Krea rounds them onto its nearest 1K or 2K canvas by area, and Luminal prices that the same way: 2K whenwidth × heightis over 2,097,152 pixels (about 2.1 MP, e.g. 2048 × 1025), else 1K. So 1920 × 1080 is 1K and 1500 × 1500 is 2K. - Thinking.
thinking_modeisfast(default),highorultra.ultraneeds 2K output; with no references Krea runs it asfast, and Luminal bills it asfasttoo.
400 ambiguous_request (or invalid_request) when:
resolutionis missing (with nowidth/height) or not1k/2k;widthorheightis sent without the other, outside 1–4096, or together withresolutionoraspect_ratio;aspect_ratiois not one of Krea's ten;thinking_modeis notfast,highorultra(the deprecatedinstant/medium/maxincluded), or isultraat 1K;priorityis anything butnormal(Krea's docs listlowandhigh, but Krea currently refuses them), ornegative_promptis over 1,024 characters;regionsorregional_editbreak the rules under Region edits below;- a field Krea does not document is sent (
num_images,webhook_url, …) — Krea would refuse it too, Luminal does so before your wallet is touched; image_urlshas more than 8 entries, an entry over 1024 characters (Krea's limit), or an entry that is neither adata:URI nor an asset URL fromPOST /assets(see next);- the body is not JSON (
415), orpromptis blank, over 10,000 characters, or missing when no region has anote.
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:
- an
https://URL thatPOST /assetsreturned to your key (Luminal recorded the image's width and height when you uploaded it; another key's asset, or any other URL, is a400); - a
data:image/…;base64,…URI, decoded and measured on the spot — but Krea caps each entry at 1024 characters, which fits no real image, so this form is for tests.
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)
| Component | 1K output | 2K 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).