> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lesson 6: Images In and Out

> Send images to a vision model and generate new images on Gloo with the Responses API: input formats, picking a capable model, and saving the result.

## Beyond Text

Many useful apps start with a picture: a photo of a flyer to turn into a calendar entry, a scanned form to read, a chart to explain. Others end with one: an illustration for a lesson or a graphic for an event page.

On Gloo, both use the same Responses request you've been using: add an image to the `input` to have a model read it, or pick an image-capable model to have it draw one.

***

## Core Concepts

### Images In: Vision

A model that can read images is called a **vision** model. You send the image as part of a user message, next to your text:

* `{"type": "input_text", "text": "..."}` for the words
* `{"type": "input_image", "image_url": "..."}` for the picture

The image can be a link to a picture online or the image itself, encoded as a base64 `data:` URI. (**Base64** is a way of writing a file's bytes as plain text so it fits inside JSON.)

Not every model can read images. In the [model catalog](https://docs.gloo.com/api-guides/supported-models.md), `supports_vision` is `true` and `input_modalities` includes `image` for those that can.

### Images Out: Generation

Image-capable models return a picture as an `image_generation_call` item in `output[]`. Its `result` field holds the image as a base64 string, which your code decodes and saves.

There are two ways to get one:

* **Call an image model directly**, such as `gloo-google-gemini-3-pro-image`. You can add optional `image_generation` settings (`quality`, `size`), which are passed to providers that support them.
* **Give a GPT-5 or GPT-6 model that supports it the `image_generation` tool** (see [Models that can use the tool](https://docs.gloo.com/api-guides/direct-responses.md#models-that-can-use-the-tool)). OpenAI's image generation runs as a tool, so the model decides when to draw and can combine the image with text in the same response. Include an `input_image` in the conversation and the tool edits that image instead of starting fresh.

### What It Costs

Responses requests are billed per token at the model's rates. A Gloo image model is billed at its catalog rates. Images drawn by the `image_generation` tool are billed at the rates OpenAI publishes for the image model that drew them, and only for images that come back. See [How image generation is billed](https://docs.gloo.com/api-guides/direct-responses.md#how-image-generation-is-billed).

***

## Get Started

```bash theme={null}
pip install openai
```

### Read an Image

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GLOO_API_KEY"],
    base_url="https://platform.ai.gloo.com/ai/v2/direct",
)

response = client.responses.create(
    model="gloo-google-gemini-3.1-pro",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "What event is this flyer for, and when is it?"},
            {"type": "input_image", "image_url": "https://example.com/flyer.jpg"},  # replace with your image's URL
        ],
    }],
)

print(response.output_text)
```

To send a file from disk instead of a link, encode it as a `data:` URI:

```python theme={null}
import base64

with open("flyer.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()

image_part = {"type": "input_image", "image_url": f"data:image/png;base64,{encoded}"}
```

### Generate an Image

```python Python theme={null}
import base64

response = client.responses.create(
    model="gloo-google-gemini-3-pro-image",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "A watercolor painting of a lighthouse at sunset."}
        ],
    }],
)

for item in response.output:
    if item.type != "image_generation_call":
        continue
    if item.status == "completed" and item.result:
        with open("lighthouse.png", "wb") as f:
            f.write(base64.b64decode(item.result))
        print("Saved lighthouse.png")
    else:
        print("The image wasn't generated. Status:", item.status)
```

```bash cURL theme={null}
curl -X POST 'https://platform.ai.gloo.com/ai/v2/direct/responses' \
  -H "Authorization: Bearer $GLOO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gloo-google-gemini-3-pro-image",
    "input": [
      { "role": "user", "content": [
        { "type": "input_text", "text": "A watercolor painting of a lighthouse at sunset." }
      ]}
    ]
  }'
```

The response holds the image in `output[]`:

```json theme={null}
{
  "output": [
    {
      "type": "image_generation_call",
      "id": "ig_...",
      "status": "completed",
      "result": "iVBORw0KGgoAAAANSUhEUgAA...<truncated base64 PNG>..."
    }
  ]
}
```

To use OpenAI's image generation instead, call a GPT-5 or GPT-6 model and attach the tool:

```python theme={null}
response = client.responses.create(
    model="gloo-openai-gpt-5-mini",
    input="A watercolor painting of a lighthouse at sunset.",
    tools=[{"type": "image_generation", "model": "gpt-image-2", "quality": "low"}],
)
```

The image arrives as the same `image_generation_call` item, alongside any text from the model.

***

## Good to Know

* **Use the Responses shape for images.** Vision and image generation are first-class on the Responses endpoints. [Direct Responses](https://docs.gloo.com/api-guides/direct-responses.md#multimodal) and the guarded [Responses](https://docs.gloo.com/api-guides/responses.md#multimodal) endpoint take the same request.
* **Look through every output item.** A response can hold text, reasoning and image items together. Pick out what you need by `type`.
* **`gpt-image-2` isn't a top-level `model`.** On Gloo, as on OpenAI's own API, it's set inside the `image_generation` tool. The request's `model` is a GPT-5 or GPT-6 model.
* **Save what you'll need again.** The image comes back in the response as base64. Decode it and store the file if your app will show it later.
* **Describe what you want to see.** Image prompts work best with concrete details: subject, style, setting, colors and mood.

***

## Key Takeaway

Images use the same Responses request as text. To read one, add an `input_image` and pick a model with `supports_vision`. To create one, call an image model or give a GPT-5 or GPT-6 model the `image_generation` tool, then decode the base64 `result`.

> [!TIP]
>
> **Try it on Gloo:** the [Responses tutorial](https://docs.gloo.com/tutorials/responses.md) includes a vision example in several languages, and [Supported Models](https://docs.gloo.com/api-guides/supported-models.md) shows which models take image input.

***

## Learn more

* [Direct Responses: Multimodal](https://docs.gloo.com/api-guides/direct-responses.md#multimodal): image input, image generation and image editing
* [Using the Guarded Responses API](https://docs.gloo.com/tutorials/responses.md): a step-by-step vision example
* [Supported Models](https://docs.gloo.com/api-guides/supported-models.md): which models read and generate images

***

## What's next

Next, you'll suggest relevant books, articles and videos from your own content.

> [card] [Lesson 7: Recommendations](https://docs.gloo.com/ai-learning-center/gloo-ai-104/recommendations.md)
>
> Ranked items from your own publishers or Gloo's publisher network.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.