The Basic Shape of an Image-Carrying Request

Sending an image to the model always follows the same pattern you saw in Lesson 1: build a list of messages, give the user message a content list, and include one input_image part alongside any input_text parts. This lesson focuses specifically on the input_image part itself — its required fields, its optional fields, and the mistakes developers make most often when constructing it.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe this image in one sentence."},
                {
                    "type": "input_image",
                    "image_url": "https://images.example.com/dog-park.jpg",
                },
            ],
        }
    ],
)

print(response.output_text)

The input_image content part has one required field for a URL-based image: image_url, a string pointing at a publicly reachable image. The model's provider fetches that URL server-side and passes the decoded image into the vision encoder. Nothing in your local Python process ever reads the image bytes in this flow — you are only passing a reference.

Why the URL Must Be Publicly Reachable

This point trips up a lot of developers building internal tools. If your image lives behind a corporate VPN, requires an authentication cookie, or is a file:// path on your own machine, a URL-based input_image will fail, because the request to fetch that URL is made from OpenAI's infrastructure, not from yours. Their servers have no access to your VPN, your session cookies, or your local filesystem.

This is precisely why the SDK also supports sending image bytes directly as base64 data instead of a URL — that path is covered in Lesson 3, and it is the one you need whenever the image is not already sitting at a public, unauthenticated URL.

Adding a detail Level

The input_image part accepts an optional detail field that controls how much visual resolution the model processes:

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What text appears in the top banner?"},
                {
                    "type": "input_image",
                    "image_url": "https://images.example.com/webpage-screenshot.png",
                    "detail": "high",
                },
            ],
        }
    ],
)

print(response.output_text)

Here, detail="high" asks the model to process the image at a finer resolution, which matters when the task depends on small details — reading fine print, distinguishing similar-looking icons, or counting small objects. The alternative, detail="low", processes a downscaled version of the image, which is cheaper and faster but may miss small text or fine detail. If you omit detail, the API applies a default behavior chosen automatically based on the image.

Why does this option exist at all, rather than the model always using maximum resolution? Because resolution is directly tied to token cost (as discussed in Lesson 1). A request that only needs to identify "is this a cat or a dog" gains nothing from high-resolution processing, so forcing every request through the expensive path would waste money and add latency across an entire application for no benefit. Exposing detail as a parameter lets you make that cost/accuracy trade-off deliberately, per request, based on what the task actually needs.

Note: The exact set of accepted detail values and their default behavior are specific to the model version you are using. Verify the current options against the official OpenAI documentation before relying on a particular default in production.

Combining Multiple Text Parts Around an Image

You are not limited to one text part before the image. You can structure a message with instructions before the image and a specific question after it, which can help the model understand the ordering of your intent:

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "system",
            "content": "You are a careful visual inspector. Only describe what is visibly present.",
        },
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Here is a photo of a shipping label."},
                {
                    "type": "input_image",
                    "image_url": "https://images.example.com/shipping-label.jpg",
                    "detail": "high",
                },
                {"type": "input_text", "text": "What is the destination postal code?"},
            ],
        }
    ],
)

print(response.output_text)

This example uses a system message (a plain string, since it contains no image) to set behavioral ground rules, then a user message with three content parts: a short text introduction, the image, and a specific question placed after it. Placing the question after the image, rather than before, often produces more focused answers, because the model processes the parts in order and the question becomes the most recent — and therefore most emphasized — piece of context immediately before it generates a response. This is not a strict rule for every case, but it is a useful default when your prompt asks a specific, narrow question about an image.

Common Mistakes

Passing the image URL as a plain string instead of inside a content part, which happens when developers try to reuse the simple input="some text" pattern and assume they can just append a URL to the string. The model receives the URL as literal text characters, not as image data, and either ignores it or hallucinates about what might be at that address. Always wrap image references in an explicit {"type": "input_image", "image_url": ...} part.

Forgetting that content must be a list once it contains an image, and instead leaving it as a bare string. A content field can be a plain string only when the message is pure text; the moment an image is involved, it must be a list of typed parts, even if there is only one text part alongside the image.

Using an inaccessible image URL — one that requires authentication, is behind a firewall, or has expired — and being confused when the API returns an error or the model reports it cannot see the image. Always confirm the URL loads successfully in an incognito browser window (i.e., with no cookies or session state) before assuming the model will be able to fetch it.

Best Practices

Set detail deliberately rather than always omitting it, especially in production code, so your cost and latency profile is predictable rather than left to a model-specific default that could change between versions.

Keep the descriptive text close to the image it refers to, especially in multi-image requests (covered in Lesson 7), so there is no ambiguity about which text applies to which image.

Validate image URLs before sending them by performing a lightweight HEAD request or catching request failures gracefully, rather than assuming every URL in your data pipeline is guaranteed to resolve.