OpenAI Images

Protocol navigation

Switch protocols here

Let AI choose

01StudioStudio UnifiedRecommendedAll five 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 model names without openai/: gpt-image-2, gpt-image-2.5-flare, or gpt-image-2.5-sunburst. gpt-image-2.5 routes to Flare.

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.

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.

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 72 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. A different request with that value returns 409. Sending this header with streaming returns 400. Stored results are retained for 72 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.