GPT Image 2

GPT Image 2 accepts a text prompt and optional reference images. Submit once, keep the returned task ID, and check that task for the finished images. It is sold on two channels, each with its own model ID; both read the same parameters.

Model IDs

Both IDs accept the same parameters and support every mode; only billing differs. See the model page for current prices. The examples below use gpt-image-2; replace it with gpt-image-2-official to bill by tokens.

Quick example

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "An amber glass bottle on a cream background, studio lighting",
    "size": "1024x1024",
    "quality": "low"
  }'

Endpoint

POST https://api.seedrouter.ai/v1/images/generations

The same endpoint handles generation, reference edits, and masked edits. The response contains a task ID, not the finished image. Keep API keys in server-side code.

Parameters

Size rules

Common choices are 1024x1024, 1536x1024, and 1024x1536. Custom dimensions must satisfy every rule:

• Width and height are multiples of 16.
• Neither edge exceeds 3840 pixels.
• The aspect ratio is between 1:3 and 3:1.
• Total area is between 655,360 and 8,294,400 pixels, inclusive.

auto leaves the output dimensions to the model. Do not send aspect ratios such as 16:9 as size.

The Playground offers Auto, Ratio and Custom controls. Ratio mode combines an aspect ratio with a 1K, 2K or 4K pixel-budget preset, then sends only the resulting size. These are UI presets, not separate API parameters: do not send resolution or aspect_ratio. For example, 16:9 + 4K sends size: "3840x2160"; 9:16 + 4K sends "2160x3840"; 1:1 + 2K sends "2048x2048". Rounding and the edge limit can reduce the pixel count for a selected tier. The exact dimensions are shown before submission.

OpenAI describes resolutions above 2560×1440 as experimental. They are accepted within the limits above; higher resolution is not a guarantee of better detail.

Quality tiers

Use low for drafts and compare results before choosing a higher tier. auto lets the model choose; it does not guarantee a particular tier or cost.

Transparent backgrounds

Transparency is in preview for GPT Image 2. For a transparent background, set background: "transparent" and use PNG. JPEG does not support transparency. Compression applies only to JPEG.

user is available for API integrations but is not shown or automatically populated in the Playground.

Optional scalar settings (n, size, quality, background, output_format, output_compression, moderation) accept null as omission. Unknown fields are rejected. input_fidelity is not configurable for GPT Image 2; reference inputs always use high fidelity. style and response_format belong to other image models and are not accepted here.

Modes

There is no separate mode parameter or editing endpoint to choose.

Edit reference images

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Make the bottle blue. Preserve the composition and lighting.",
    "images": [{"image_url": "https://example.com/reference.png"}],
    "mask": {"image_url": "https://example.com/mask.png"},
    "output_format": "jpeg",
    "output_compression": 90
  }'

Replace both example URLs with your own accessible images. Omit mask for a reference edit without a selected region.

Media inputs

This API accepts URL references only. OpenAI Files IDs, base64 data URLs, and multipart uploads are not accepted. The Playground uploads selected files to storage before submitting their URLs.

Reference images must be public HTTP(S) URLs pointing to PNG, JPEG, or WebP files smaller than 50 MB each. A mask must be a PNG smaller than 4 MB, with the same dimensions as the first reference image; its transparent area marks what to edit. A mask guides the model and does not guarantee pixel-perfect boundaries. For multiple references, the mask applies to the first image. URL media is validated during processing; invalid or inaccessible media can produce a failed task.

The Playground uploads selected files and submits their URLs. API requests use JSON URL objects: do not send file bytes, base64, data: URLs, blob: URLs, or multipart form data.

Pricing dimensions

Check the model pricing section for current rates. gpt-image-2 (Standard) charges one flat price per delivered image, whatever the quality, size, or prompt. On gpt-image-2-official (Official), the final cost depends on input and output usage: quality, output dimensions, reference images, prompt length, and image count can all affect it.

The Playground estimate uses a measured sample and current rates; it is not a guaranteed quote. View final charges in your account usage history. Failed tasks are not charged.

Output schema

Submission returns a task reference:

{
  "id": "task_...",
  "model": "gpt-image-2",
  "status": "processing",
  "created_at": 1789970508
}

Poll the task

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

Poll at a modest interval, such as every three seconds, until status is completed or failed. A network timeout while polling does not mean generation failed: keep the task ID and resume checking it. Do not create another task to check progress.

Complete polling example

Run this after the Python submission example above. It uses the returned task_id and waits up to ten minutes. Reaching this local deadline stops polling only; retain the ID and resume querying the same task.

import time

print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Completed task

A completed task returns hosted image URLs and usage:

{
  "id": "task_...",
  "model": "gpt-image-2",
  "status": "completed",
  "created_at": 1789970508,
  "finished_at": 1789970538,
  "output": {
    "created": 1789970532,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.png"}],
    "usage": {
      "input_tokens": 29,
      "output_tokens": 196,
      "total_tokens": 225
    }
  }
}

This API uses asynchronous task delivery. It is not a synchronous Images SDK replacement; stream and partial_images are not supported.

Errors

Requests rejected before a task is created return an HTTP error with an error object. A task that fails after acceptance returns HTTP 200 when queried, with status: "failed" and an error object.

See the shared error catalog for codes, HTTP statuses, and retry guidance. All model APIs use the same error envelope.

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60002,
    "message": "Generation could not be completed. Please try again."
  }
}

If submission itself times out, check your task history before submitting again: the first request may have been accepted.

Tips

• Describe materials, composition, and lighting in the prompt.
• For an edit, specify both the change and what should remain unchanged.
• Use a mask when only a selected area should change.
• Save returned images to your own storage when you need a durable copy.

Related

• GPT Image 2 Playground and pricing
• Download OpenAPI
• Copyable Markdown