GPT Image 2.5 Sunburst API
OpenAIimage$0.084 / runSubmit a GPT Image 2.5 Sunburst run over HTTP, then poll it or take a webhook. Results are files on media.ezflows.io. Try it in the playground first.
Async: the POST answers at once with a request id. Poll it, or take the webhook.
- 01
Submit
Parameters at the top level of the JSON body. Answers 202 with a request id.
curlPOST /v1/models/gpt-image-2.5-sunburst curl -X POST https://api.ezflows.io/v1/models/gpt-image-2.5-sunburst \ -H "Authorization: Bearer $EZFLOWS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A straight-down product still-life photograph on a brushed grey concrete surface. A glossy black vinyl record is half-slid out of a matte kraft-brown album sleeve. The sleeve is a modernist jazz cover: a large clean title '\''MIDNIGHT LATITUDES'\'' across the top in condensed sans-serif, an artist line '\''The Corner Sessions Quartet'\'' beneath it, and a five-song tracklist down the right edge reading '\''1. Blue Meridian 2. Harbor Lights 3. Slow Tide 4. Northbound 5. Last Call'\''. The record'\''s cream paper center label reads '\''SIDE A'\'' with a catalog number '\''CS-014'\''. Concentric grooves catch a low raking light; faint paper grain on the cardboard and light dust on the vinyl. Colour palette of deep teal, mustard and off-white.", "size": "1536x1024" }' # 202 Accepted, at once — it never waits for the model: # {"request_id": "req_8f2a41c9b70e4d15", "status": "queued", # "poll_url": "https://api.ezflows.io/v1/requests/req_8f2a41c9b70e4d15"} - 02
Poll
Same bearer header, every few seconds, until the status is final.
curlGET /v1/requests/:id REQUEST_ID=req_8f2a41c9b70e4d15 # from the POST while :; do BODY=$(curl -s https://api.ezflows.io/v1/requests/$REQUEST_ID \ -H "Authorization: Bearer $EZFLOWS_API_KEY") STATUS=$(echo "$BODY" | jq -r .data.status) case "$STATUS" in succeeded|failed|cancelled) break ;; esac sleep 3 done echo "$BODY" | jq -r '.data.output.artifacts[].url' # media.ezflows.io, kept 90 days - 03
Response
Files are on media.ezflows.io, kept 90 days. A failed run says why and costs nothing.
json200 · succeeded { "data": { "id": "req_8f2a41c9b70e4d15", "model_slug": "gpt-image-2.5-sunburst", "status": "succeeded", "http_status": 200, "cost": 0.084177, "auth_method": "api_key", "error": null, "submitted_at": "2026-09-12T18:07:21.114Z", "queue_started_at": "2026-09-12T18:07:21.402Z", "execution_started_at": "2026-09-12T18:07:22.010Z", "first_byte_at": "2026-09-12T18:07:52.871Z", "finished_at": "2026-09-12T18:07:55.203Z", "io_deleted_at": null, "canvas_id": null, "canvas_node_id": null, "client_attempt_id": null, "idempotency_key": null, "input": { "prompt": "A straight-down product still-life photograph on a brushed grey concrete surface. A glossy black vinyl record is half-slid out of a matte kraft-brown album sleeve. The sleeve is a modernist jazz cover: a large clean title 'MIDNIGHT LATITUDES' across the top in condensed sans-serif, an artist line 'The Corner Sessions Quartet' beneath it, and a five-song tracklist down the right edge reading '1. Blue Meridian 2. Harbor Lights 3. Slow Tide 4. Northbound 5. Last Call'. The record's cream paper center label reads 'SIDE A' with a catalog number 'CS-014'. Concentric grooves catch a low raking light; faint paper grain on the cardboard and light dust on the vinyl. Colour palette of deep teal, mustard and off-white.", "size": "1536x1024" }, "output": { "artifacts": [ { "index": 0, "kind": "image", "contentType": "image/png", "url": "https://media.ezflows.io/outputs/<account>/req_8f2a41c9b70e4d15/0.png" } ] } } } - 04
Webhook
Skip polling: we POST the result to your endpoint, at least once.
- Register
- Create an endpoint under Webhooks in the dashboard; the signing secret is shown once.
- Events
- request.succeeded · request.failed · request.cancelled
- Headers
- ezflows-event-id (dedupe on it) · ezflows-timestamp (unix seconds) · ezflows-signature t=<ts>,v1=<hex HMAC-SHA256 of "<ts>.<raw body>">
- Verify
- Over the exact bytes received, in constant time; reject anything older than five minutes.
- Respond
- Any 2xx within 10 s. Redirects are not followed.
- Retries
- Five, with backoff: 30 s · 60 s · 2 min · 4 min · 8 min. Disabled after five consecutive dead deliveries.
jsonDelivery body { "id": "82cf46a4-841e-41d6-b3c7-facc937d3252", "type": "request.succeeded", "created_at": "2026-09-12T18:07:55Z", "data": { "id": "req_8f2a41c9b70e4d15", "model_slug": "gpt-image-2.5-sunburst", "status": "succeeded", "cost": 0.084177, "output": { "artifacts": [ { "url": "https://media.ezflows.io/…/0.png" } ] } } }curlverify.sh # Create the endpoint under Webhooks in the dashboard; the signing secret is shown once. # ezflows-signature: t=<ts>,v1=<hex HMAC-SHA256 of "<ts>.<raw body>"> # body.json = the exact bytes received. Reject anything older than five minutes. EXPECTED=$({ printf '%s.' "$TS"; cat body.json; } \ | openssl dgst -sha256 -hmac "$EZFLOWS_WEBHOOK_SECRET" -r | cut -d' ' -f1) [ "$EXPECTED" = "$V1" ] && echo "valid" || echo "reject"
Parameters 9
| Name | Type | Default | Allowed | Description |
|---|---|---|---|---|
| promptrequired | string | A straight-down product still-life photograph on a brushed grey concrete surface. A glossy black vinyl record is half-slid out of a matte kraft-brown album sleeve. The sleeve is a modernist jazz cover: a large clean title 'MIDNIGHT LATITUDES' across the top in condensed sans-serif, an artist line 'The Corner Sessions Quartet' beneath it, and a five-song tracklist down the right edge reading '1. Blue Meridian 2. Harbor Lights 3. Slow Tide 4. Northbound 5. Last Call'. The record's cream paper center label reads 'SIDE A' with a catalog number 'CS-014'. Concentric grooves catch a low raking light; faint paper grain on the cardboard and light dust on the vinyl. Colour palette of deep teal, mustard and off-white. | — | Text describing the image. Supports in-image typography across scripts — lead with subject, style, lighting. |
| image_urls | string[] | [] | image urls | Optional reference images to edit or draw context from. Providing any image switches to edit mode. |
| size | enum | 1536x1024 | 1024x1024 · 1536x1024 · 1024x1536 · 1280x960 · 960x1280 · 1536x864 · 864x1536 · 2048x2048 · 2048x1152 · 1152x2048 · 3840x2160 · 2160x3840 · auto | Output resolution (WIDTHxHEIGHT). Each edge must be a multiple of 16, aspect ratio between 1:3 and 3:1, longest edge at most 3840, and total pixels between 655,360 and 8,294,400. "Auto" lets the model pick. |
| mask_image_url | string | — | one image url | Optional mask for surgical inpainting, used only alongside a reference image. Must be a PNG with an alpha channel, matching the reference image's dimensions: the transparent areas are regenerated, everything opaque stays pixel-perfect. A flat black-and-white mask with no alpha channel is rejected. |
| quality | enum | high | low · medium · high | Rendering fidelity. "High" keeps typography crisp; use lower values only for previews. |
| background | enum | opaque | opaque · transparent · auto | "Opaque" renders a filled background; "Transparent" returns a PNG or WEBP with an alpha channel; "Auto" lets the model decide. |
| moderation | enum | auto | low · auto | Content filter strictness. "Auto" is the safe default. |
| output_format | enum | png | png · jpeg · webp | "PNG" for crisp text, "WEBP" for smaller size, "JPEG" for broad compatibility. |
| output_compression | integer | 100 | 0–100 | Compression level 0-100. 100 preserves text crispness; lower values reduce file size. |
File inputs (image_urls: image urls · mask_image_url: one image url) take URLs. Upload the raw file to POST /v1/uploads with its own Content-Type and pass the url it returns. Inputs are kept 90 days.