Image generation and editing API

Beginner: generation is not editing

Create a new image with POST /v1/images/generations. Send reference images, masks, or revision instructions to POST /v1/images/edits. Model IDs, dimensions, quality values, output formats, and maximum counts vary by model and channel, so confirm the exact entry in the model marketplace. The gpt-image-2 introduction is on the OpenAI image capability page. /v1/images/variations is not implemented here.

Minimal text-to-image request

Begin with one image and a standard size. A model may support url, b64_json, or only a subset of response formats.

Copycurl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A layered paper-cut white rabbit in a warm studio",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

A successful response normally returns data[] with either url or b64_json. Branch on the field that is actually present. When the site persists an asynchronous image result, query GET /v1/images/generations/result?request_id=... only with the identifier returned by the original operation.

Reference edits and file inputs

Multipart is the clearest upload contract. Enforce file type, pixel, byte, and count limits, and stream large bodies instead of buffering them.

Copycurl "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Keep the composition and change the background to a rainy neon street" \
  -F "image=@input.png" \
  -F "response_format=url"

Some channel adapters also accept an HTTPS URL, data URL, or Base64 reference in JSON. Treat remote retrieval as SSRF-sensitive and do not call /v1/files; that Files API is not implemented by this gateway.

Failures, retries, and result lifetime

A 400 usually means an unsupported size, format, count, reference, or model capability. 413 means the body is too large. 429 can represent rate, concurrency, quota, or balance constraints. Retry only transient failures. A timed-out create request may already have produced and billed an image, so record the Request-ID, prompt hash, model, size, quality, and an application idempotency key before deciding to submit again.

Signed result URLs can expire. Stream them into controlled object storage, record content type, byte length, hash, task origin, and deletion time. Estimate decoded size before accepting Base64 so the JSON string, encoded bytes, and decoded file are not all retained without bounds.

Expert: quality, safety, and cost governance

Maintain an evaluation set for text rendering, identity consistency, brand colors, reference fidelity, transparency, and sensitive content. Run a canary before changing models. Treat prompts, inputs, and outputs as sensitive data with authorization, moderation, retention, and deletion controls. Cost records should include model, count, size, quality, reference count, and retries. Limit concurrent generations, response size, and download bandwidth, and cancel upstream work when a disconnected client no longer needs it.