Images and vision | OpenAI API

Recent language models can process image inputs and analyze them—a capability known as vision. GPT Image models can use text and image inputs to create new images or edit existing ones.

Choose an endpoint based on whether you want to analyze images or generate them:

To learn more about the input and output modalities supported by our models, refer to our models page.

With the Images API, choose gpt-image-2.5-sunburst to generate images from text or edit existing images. With the Responses API, choose a mainline model that supports the image generation tool; the tool handles GPT Image model selection.

from openai import OpenAI
import base64

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Generate an image of gray tabby cat hugging an otter with an orange scarf",
    tools=[{"type": "image_generation"}],
)

# Save the image to a file
image_data = [
    output.result
    for output in response.output
    if output.type == "image_generation_call"
]

if image_data:
    image_base64 = image_data[0]
    with open("cat_and_otter.png", "wb") as f:
        f.write(base64.b64decode(image_base64))

Using world knowledge for image generation

GPT Image models can draw on world knowledge without a reference image. For example, a prompt for a cabinet of semi-precious stones can produce a scene containing recognizable gemstones such as amethyst, rose quartz, and jade.

Use a vision-capable model to describe images, read visible text, and answer questions about objects, shapes, colors, or textures. Account for the model’s limitations when using its answers.

Giving a model images as input

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "what's in this image?"},
                {
                    "type": "input_image",
                    "image_url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg",
                },
            ],
        }
    ],
)

print(response.output_text)

Image input requirements

Use supported image files that are clear enough for the model to analyze.

For patch-based image inputs, the API supports up to 30,000 patches per image after applying the resizing rules for the selected model and detail level. This limit applies across supported detail levels and to each image separately, not to the combined patch count of the request.

Lower model- and detail-specific resizing budgets still apply. Images that exceed the 30,000-patch limit after processing are rejected, not automatically resized to meet it. Reduce the image’s dimensions and try again.

Image tokens and the rest of your prompt must also fit the model’s input and context limits. A token estimate does not guarantee that a request meets every input limit. Image use must comply with our usage policies.

Choose an image detail level

The detail parameter controls image preprocessing. Supported values depend on the model: low, high, original, or auto. If you omit the parameter, it defaults to auto in both the Responses API and the Chat Completions API. The model sizing table shows the corresponding behavior.

{
    "type": "input_image",
    "image_url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg",
    "detail": "original"
}

Use the following guidance to choose a detail level:

For tasks that require fine visual detail or precise coordinates, such as optical character recognition (OCR), small-object detection, or computer use, use "detail": "original" when supported. Original detail can still resize images to meet the model’s pixel-dimension limit or resizing patch budget, but not to meet the separate 30,000-patch rejection limit. For coordinate-sensitive tasks, resize images to fit those limits before sending them and map returned coordinates back to the original image. See the Computer use guide for coordinate handling.

Model sizing behavior

The following table summarizes sizing behavior for general-purpose vision models. Other models and specialized variants can use different limits. All resizing preserves aspect ratio without enlarging smaller images.

Vision models convert image inputs into billable input tokens. The image input cost calculator and patch/tile rules in this section cover vision-model inputs, not GPT Image generation or editing. See GPT Image model inputs for that separate pricing.

Image tokens also count toward your tokens per minute (TPM) limits. The calculator estimates one image at standard input rates; it does not include the rest of your prompt or model output.

Image input cost calculator

Use the image input cost calculator to estimate input tokens and cost for one image by model, image size, and detail level.

Patch-based image tokenization

Some models tokenize images by covering them with 32px x 32px patches. Many model and detail-level combinations define a resizing patch budget. First, the API fits the image within the selected detail level’s pixel-dimension limit, preserving aspect ratio and rounding to integer pixels without enlarging smaller images. The token cost is then determined as follows:

A. Compute how many 32px x 32px patches are needed to cover the image after applying the pixel-dimension limit. A patch may extend beyond the image boundary.

patch_count = ceil(width/32)×ceil(height/32)

B. When the selected model and detail level specify a resizing patch budget, scale the image down proportionally if it exceeds that budget. Otherwise, skip this step. Adjust the scale to stay within budget after converting to integer pixel dimensions and computing patch coverage. Keep full precision until calculating the final dimensions.

shrink_factor = sqrt((32^2 * patch_budget) / (width * height))
adjusted_shrink_factor = shrink_factor * min(
  floor(width * shrink_factor / 32) / (width * shrink_factor / 32),
  floor(height * shrink_factor / 32) / (height * shrink_factor / 32)
)

C. If step B resized the image, round down the final scaled width and height to integer pixels. Compute the patches needed to cover the resulting image. This is the image-token count before applying the model multiplier. When a patch budget applies, this count stays within that budget.

resized_patch_count = ceil(resized_width/32)×ceil(resized_height/32)

If this count exceeds 30,000 patches, the API rejects the request. Check this limit before applying the token multiplier.

D. Multiply the patch count by the model’s multiplier and round up to get the billable image input tokens. Apply the model’s input price to those tokens once; the multiplier does not apply to other prompt tokens or to the price again.

For gpt-4.1-mini, this applies to the 2025-04-14 snapshot.

* Deprecated and scheduled for shutdown. See the deprecation schedule for dates and replacements. These models aren’t included in the calculator or the model sizing table above.

Image token calculation examples for gpt-6-astra with detail: high

This combination uses a 65,535-pixel maximum dimension, a 2,500-patch budget, and a 1.2× multiplier.

• A 1024 × 1024 image needs 32 × 32 = 1024 patches. No resizing is needed. The billable image input is ceil(1024 × 1.2) = 1229 tokens.
• A 2048 × 2048 image initially needs 64 × 64 = 4096 patches. The patch budget reduces it to 1600 × 1600 pixels, or 50 × 50 = 2500 patches. The estimate is ceil(2500 × 1.2) = 3000 tokens.
• A 4096 × 512 image stays at its original size: 128 × 16 = 2048 patches and ceil(2048 × 1.2) = 2458 tokens.

Floating-point rounding in billing can make the final count differ from the estimate by one token.

Tile-based image tokenization

The models in this table use a base token count plus tokens for image tiles:

* Deprecated and scheduled for shutdown. See the deprecation schedule for dates and replacements. These models aren’t included in the calculator or the model sizing table above.

With "detail": "low", an image costs only the model’s base tokens, regardless of dimensions. With "detail": "high" or "detail": "auto":

• Scale down to fit in a 2048px x 2048px square, maintaining aspect ratio. Smaller images are not enlarged.
• If the shortest side exceeds 768px, scale it down to 768px and round down the other dimension.
• Count the 512px squares needed to cover the image. Each square uses the model’s tile tokens.
• Add the model’s base tokens to the tile tokens.

GPT Image model inputs

GPT Image models use separate image-token pricing for generation and editing. The vision calculator does not estimate their input or output costs. For current rates, see image generation pricing; for generation and editing workflows, see the Image generation guide.

GPT Image 1

gpt-image-1 was shut down on October 23, 2026. The following input-token rules are retained for historical cost comparisons. See the deprecation notice for replacement models.

For legacy requests, use tile-based image sizing, but scale the shortest side down to 512px instead of 768px. Token use depends on the image dimensions and the input_fidelity parameter in the Images API.

When input fidelity is set to low, the base cost is 65 image tokens, and each tile costs 129 image tokens. When using high input fidelity, we add a set number of tokens based on the image’s aspect ratio in addition to the image tokens described above.

• If your image is square, we add 4160 extra input image tokens.
• If it is closer to portrait or landscape, we add 6240 extra tokens.

For historical image input-token prices, see the GPT Image 1 model page.

Vision models can make mistakes. Account for these limitations when designing your application:

• Medical images: The model is not suitable for interpreting specialized medical images like CT scans and shouldn’t be used for medical advice.
• Non-English: The model may not perform optimally when handling images with text of non-Latin alphabets, such as Japanese or Korean.
• Small text: Enlarge text within the image to improve readability. When available, using "detail": "original" can also help performance.
• Rotation: The model may misinterpret rotated or upside-down text and images.
• Visual elements: The model may struggle to understand graphs or text where colors or styles—like solid, dashed, or dotted lines—vary.
• Spatial reasoning: The model struggles with tasks requiring precise spatial localization, such as identifying chess positions.
• Accuracy: The model may generate incorrect descriptions or captions in certain scenarios.
• Image shape: The model struggles with panoramic and fisheye images.
• Metadata and resizing: The model doesn’t process original file names or metadata. Images may be resized before analysis, including with original detail. See Model sizing behavior for the limits that apply to each model.
• Counting: The model may give approximate counts for objects in images.
• CAPTCHAs: For safety reasons, our system blocks the submission of CAPTCHAs.