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

# builtin__generate_image

> Generates images with the image model, or edits the images it's given, and returns each as a file reference.

Needs an [image model](https://graph.mintlify.site/getting-started/models.md#image-models) on the `image` role, and appears in the tool catalog only once one is configured. Pass refs from earlier results in `images` to edit or combine them, with a prompt that says what to change. A value the model doesn't support, such as an `aspect_ratio` or `size` it can't produce, is a tool error that lists the values it does support, so an agent can correct the call and retry.

With `path`, each image is also written into the workspace, with the extension of the type the model returned (a JPEG asked for at `site/hero.png` lands at `site/hero.jpg`, and the result's `path` says where); when `count` is over 1, later images get `-2`, `-3` and so on before the extension. A path must be relative and stay inside the workspace.

| Loaded | Kind | Effect |
| - | - | - |
| Always | `image` | Not marked read-only |

## Input

**prompt** `string` *required*

What to draw, or what to change in the given images.

**images** `string[]`

Refs of images to edit or use as references, such as blob:sha256-….png from an earlier tool result.

**aspect\_ratio** `string`

Width to height, such as "1:1", "16:9" or "9:16". Omit for the model's default.

**size** `string`

Output resolution, such as "1K", "2K" or "4K" (uppercase K). Omit for the model's default.

**count** `integer` (default: 1)

How many images to generate.

**path** `string`

A path inside the workspace to also save the image to, such as site/hero.png. The extension follows the images type, so a JPEG lands at site/hero.jpg. With a count over 1, later images get -2, -3 before the extension.

## Output

The images the model drew, plus any text it wrote alongside them.

**images** `object[]`

One entry per image, in the order they were generated.

**images.\[].ref** `string`

The image's file reference, such as `blob:sha256-….png`. Put it in a reply as a markdown image's URL, or pass it to another tool.

**images.\[].mime** `string`

The image's type, such as `image/png`.

**images.\[].bytes** `integer`

The file's size.

**images.\[].width** `integer`

Width in pixels.

**images.\[].height** `integer`

Height in pixels.

**images.\[].path** `string`

Where the image was saved in the workspace, when the call set `path`.

**text** `string`

Text the model returned with the images, when it wrote any.

```yaml Plan step theme={null}
- id: E1
  tool_name: builtin__generate_image
  input:
    prompt: "{{input.prompt}}"
```

```bash Inspect theme={null}
dive tool show builtin__generate_image
```


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