GPT Image 2.5 Sunburst API

OpenAIimage$0.084 / run

Submit 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.

  1. 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"}
  2. 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
  3. 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"
            }
          ]
        }
      }
    }
  4. 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

NameTypeDefaultAllowedDescription
promptrequiredstringA 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_urlsstring[][]image urlsOptional reference images to edit or draw context from. Providing any image switches to edit mode.
sizeenum1536x10241024x1024 · 1536x1024 · 1024x1536 · 1280x960 · 960x1280 · 1536x864 · 864x1536 · 2048x2048 · 2048x1152 · 1152x2048 · 3840x2160 · 2160x3840 · autoOutput 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_urlstring—one image urlOptional 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.
qualityenumhighlow · medium · highRendering fidelity. "High" keeps typography crisp; use lower values only for previews.
backgroundenumopaqueopaque · transparent · auto"Opaque" renders a filled background; "Transparent" returns a PNG or WEBP with an alpha channel; "Auto" lets the model decide.
moderationenumautolow · autoContent filter strictness. "Auto" is the safe default.
output_formatenumpngpng · jpeg · webp"PNG" for crisp text, "WEBP" for smaller size, "JPEG" for broad compatibility.
output_compressioninteger1000–100Compression 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.