OpenAI Images

Protocol navigation

Switch protocols here

Let AI choose

01StudioStudio UnifiedRecommendedAll six models, job progress, results, and cancellation.02OpenAIOpenAI ImagesCurrentExisting OpenAI Images workflows and SDKs.03GoogleGemini NativeGoogle SDK, multi-turn editing, and native multimodal content.

import jsonfrom openai import OpenAIapi_key = "YOUR_API_KEY"api_base = "https://api.1route.dev"payload = {    "model": "gpt-image-2.5-flare",    "prompt": "Editorial portrait of a woman in profile beside a wind-bent tree, late afternoon light, deep cobalt coat, pale concrete wall, subtle film grain, restrained color palette, clean composition, vertical 4:5.",    "size": "auto",    "n": 1,    "output_format": "png",    "response_format": "b64_json"}client = OpenAI(api_key=api_key, base_url=f"{api_base}/v1", max_retries=0, timeout=1500)response = client.images.generate(**payload)result = response.model_dump(mode="json", exclude_none=True)print(json.dumps(result, ensure_ascii=False, indent=2))

Generate an image

Send JSON with Authorization: Bearer YOUR_API_KEY. A non-streaming request waits for generation and returns images in data[].

{
  "model": "gpt-image-2.5-flare",
  "prompt": "A product photograph of a white ceramic cup, soft side light, pale gray background",
  "size": "1024x1024",
  "quality": "high",
  "n": 1,
  "output_format": "png",
  "response_format": "b64_json"
}

Use base model names without openai/: gpt-image-2 and the 2.5 or 2.6 families. Both 2.5 and 2.6 offer Flare and Sunburst; each bare family name resolves to its Flare variant. Available models and sizes depend on the selected channel's image catalog.

Use a base model name and select dimensions with size; no size suffix is needed. The catalog's supported tiers and automatic-size flag determine the available options. For example, the Adobe channel offers only 1K and automatic sizing.

Dimensions and quality

Common sizes include 1024x1024, 1536x1024, 1024x1536, 2048x2048, and 3840x2160. Pixel dimensions map to a 1K / 2K / 4K routing tier. size sets dimensions; quality sets rendering quality.

For native custom dimensions, both edges must be multiples of 16, the longest edge at most 3840, the aspect ratio no greater than 3:1, and total pixels between 655,360 and 8,294,400. Choose dimensions within these limits for predictable output.

Official GPT Image 2.6 capabilities

gpt-image-2.6-flare and gpt-image-2.6-sunburst use the parameters below; the site's bare gpt-image-2.6 name resolves to Flare. Availability, supported sizes, and pricing come from the selected channel's current image catalog.

For 2.6 generation and editing, complexity accepts low, medium, or high; omission uses the upstream default high. It controls image complexity separately from quality. The playground's Additional JSON fields can carry this field when using a model that supports it.

For 2.6 generation only, output_format also accepts svg (vector) and gif (animation). SVG requires n: 1. Neither format supports streaming, partial_images, output_compression, or prompt_rewriter; neither is an edit output format. GIF alone accepts frame_count from 2–64 (default 9) and frame_duration_ms from 20–2000 (default 200), rounded by the upstream to 10 ms increments.

The conditional examples below use the same request constructor as the browser and code generator. The playground retains raster format choices for the currently offered models.

{  "complexity": "medium",  "model": "gpt-image-2.6-flare",  "prompt": "A simple flat vector icon of a white ceramic cup",  "size": "auto",  "n": 1,  "output_format": "svg",  "response_format": "b64_json"}

{  "complexity": "medium",  "frame_count": 9,  "frame_duration_ms": 200,  "model": "gpt-image-2.6-flare",  "prompt": "A seamless looping animation of steam rising from a ceramic cup",  "size": "auto",  "n": 1,  "output_format": "gif",  "response_format": "b64_json"}

Decode Base64 directly to output.svg or output.gif, or download the original URL. SVG uses image/svg+xml; GIF uses image/gif. Preserve the original bytes to retain vector data or animation. Read actual output metadata from the response; do not infer usage or billing from requested frames.

See the official image-generation guide for model capabilities.

Python SDK

Install openai. Append /v1 to the SDK base URL, including when using the alternate host.

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.1route.dev/v1",
    max_retries=0,
    timeout=1500,
)
result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="A white ceramic cup, soft side light, pale gray background",
    size="1024x1024",
    response_format="b64_json",
)
Path("output.png").write_bytes(base64.b64decode(result.data[0].b64_json))

Reference images

The endpoint accepts uploaded files or JSON image addresses. References preserve their order; distinguish them as the first and second image in your prompt.

Local files

Use multipart/form-data with repeated image[] fields, or image for a single file. Other parameters are form fields. Let your HTTP library set Content-Type and its boundary.

from pathlib import Path

result = client.images.edit(
    model="gpt-image-2.5-sunburst",
    prompt="Preserve the person in the first image and dress her in the second image's coat",
    image=[
        ("person.png", Path("person.png").read_bytes(), "image/png"),
        ("coat.png", Path("coat.png").read_bytes(), "image/png"),
    ],
    size="1024x1536",
    response_format="b64_json",
)
Path("edited.png").write_bytes(base64.b64decode(result.data[0].b64_json))

Up to 16 references are accepted: PNG, JPEG, or WebP, at most 50 MiB each. The total request body limit is 512 MiB. Base64 encoding increases the request size.

URLs and Data URLs

Send application/json with images[].image_url. Public URLs and complete Data URLs can be mixed:

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the cup's logo; use the second image's table as the background",
  "images": [
    { "image_url": "https://your-image-host.example/cup.png" },
    { "image_url": "data:image/png;base64,<image bytes>" }
  ],
  "size": "1024x1024",
  "response_format": "url"
}

Use the SDK's generic request method for JSON edits, or select httpx, requests, or fetch in the playground. JSON images is distinct from the SDK's file parameter image.

from openai.types import ImagesResponse

result = client.post("/images/edits", body=payload, cast_to=ImagesResponse)
print(result.data[0].url)

The server downloads image URLs. file_id is not accepted.

Masks and local edits

A mask applies to the first reference. Transparent PNG regions identify the edit area. Its dimensions must match the first reference and its size must not exceed 4 MiB. Upload it as the mask file field, or use this JSON field:

{
  "mask": { "image_url": "data:image/png;base64,<mask bytes>" }
}

Describe the intended edit in prompt as well. gpt-image-2 always processes references at high fidelity; omit input_fidelity.

Markup annotation layers

Supporting GPT Image 2.5 and 2.6 models accept one markup annotation layer for an edit. This is a transparent PNG over the first reference image, distinct from a mask. It must have the same dimensions as that reference after applying image orientation, contain at least one non-opaque pixel, and be at most 50 MiB. Both the first reference and the markup must be at most 16,777,216 pixels. Do not combine markup with mask or prompt_rewriter.

For multipart, upload a single PNG file part named markup. For JSON edits, use markup.image_url with a public URL or a complete PNG Data URL:

{
  "model": "gpt-image-2.5-flare",
  "prompt": "Apply the changes indicated by the annotation layer, preserving the rest of the image",
  "images": [{ "image_url": "https://your-image-host.example/product.png" }],
  "markup": { "image_url": "data:image/png;base64,<transparent PNG annotation bytes>" }
}

In the playground, provide the reference normally and put markup in Additional JSON fields. Uploaded references are encoded as Data URLs in this JSON request. markup.file_id is unsupported on this site and returns unsupported_file_id with param=markup.file_id; use image_url instead. Markup does not replace the required reference image.

Response data

Base64

{
  "created": 1788940800,
  "data": [{ "b64_json": "<complete image bytes>" }],
  "size": "1024x1024",
  "quality": "high",
  "output_format": "png",
  "usage": {
    "input_tokens": 20,
    "output_tokens": 1000,
    "total_tokens": 1020,
    "input_tokens_details": { "text_tokens": 20, "image_tokens": 0 }
  }
}

created is Unix seconds. Iterate over data[] and decode b64_json into bytes. It has no Data URL prefix. The playground folds the display but copies and downloads the complete payload.

size, quality, background, and output_format describe the generated output when supplied upstream. usage measures tokens, not currency; input_tokens_details separates text and image input. These metadata fields may be absent. If supplied, revised_prompt contains the rewritten prompt used for generation.

Image URLs

Set response_format: "url" and read data[].url:

{
  "created": 1788940800,
  "data": [{ "url": "https://api.1route.dev/v1/images/files/media_example" }]
}

URL delivery is provided by this service. Images are retained for 24 hours; expired media returns 410 result_expired. Download them for long-term storage. Media addresses support GET and HEAD. Encoding and delivery are independent: JPEG can also be returned as Base64.

Streaming

Generation and editing accept stream: true. partial_images, from 0 to 3, requests preview images. A fast generation may produce fewer previews than requested.

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="A coffee poster with a handwritten title",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type == "image_generation.completed":
        Path("output.png").write_bytes(base64.b64decode(event.b64_json))

HTTP responses use SSE. Generation emits image_generation.partial_image and image_generation.completed; editing uses image_edit.partial_image and image_edit.completed. partial_image_index identifies a preview. Save the completed image as the final result. An error event can arrive after HTTP 200.

Native streams do not return Studio job IDs or expose its status and cancellation endpoints. Use Studio Unified when you need durable job tracking.

Idempotency and errors

Non-streaming requests accept Idempotency-Key. The same API key, idempotency value, and request wait for or reuse the original result; if the client disconnects, using the same value again still waits for or reuses the original job instead of generating again. A different request with that value returns 409. Sending this header with streaming returns 400. Stored results are retained for 24 hours.

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Common edit codes include edit_image_required, edit_too_many_images, edit_image_too_large, and edit_mask_dimensions_mismatch. Content errors may include moderation_blocked; revise the prompt or input rather than repeating the same request.