Input Formats

~22 min · input, messages, multimodal

Level 0Tokenizer

0 XP0/54 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

The input parameter is flexible — it accepts a simple string, a message array, or structured multimodal content.

3. Structured Multimodal Content

The flexibility of accepting a plain string makes simple use cases trivial, while the array format provides full control for complex multi-turn or multimodal scenarios.

String for one-shot, list for everything else

If you have a single user prompt with no images and no history, the string form (input="What is 2+2?") is fine. The moment you need an image, file, multi-turn chat, or fine-grained role control, switch to the message list with typed content parts.

The typed content parts (input_text, input_image, input_file) make the multimodal shape explicit at the wire level. No more 'is this a string or a list of dicts?' guessing — the type tag tells the API exactly what to expect.

Code

Plain string input·python

response = client.responses.create(
    model="gpt-5.4",
    input="Explain quantum entanglement in simple terms."
)
print(response.output_text)

Message-list input with input_text and input_image·python

response = client.responses.create(
    model="gpt-5.4",
    input=[
        {"role": "developer", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is 2 + 2?"},
    ]
)

Example 3·python

response = client.responses.create(
    model="gpt-4.1",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Describe this image:"},
            {"type": "input_image", "image_url": "https://example.com/img.jpg", "detail": "high"},
            {"type": "input_file", "file_id": "file-abc123"},
        ]
    }]
)

External links

Input format reference

Exercise

Send the same instruction three ways: (1) instructions= top-level, (2) developer-role message, (3) prepended user message. Compare the assistant outputs side-by-side. Which shape steers behavior most reliably?

Progress

Progress is local-only — sign in to sync across devices.

← Previousresponses.create() vs chat.completions.create()Next →Built-in Tools

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.