Generate and edit images

Give an agent Generate an Image (generate_image) to create images from a description or edit existing images. Each result is saved as a downloadable run file that the agent can use in later work.

Enable image generation

Assign Generate an Image in the agent's tool selection, then save the agent. Describe the subject, composition, style, dimensions, and intended use in your request. For example:

Create a square illustration of a small orange delivery robot for a presentation. Use a simple geometric style, leave room around the subject, and save it as a PNG named delivery-robot.png.

The tool can produce one to four images per call in PNG, JPEG, or WebP format. Its defaults are one 1024 × 1024 PNG at medium quality. Generation can take several minutes and uses the run's budget and the workspace's run file storage.

Choose an image model

The agent chooses an image model for the tool call. You can name a preferred model in your request or the agent's instructions.

Both models accept reference images, masks, and transparent backgrounds. Use low or medium quality for drafts, or high, xhigh, or max when more detail is worth the additional time and budget. Auto lets the model choose the quality.

Edit or make variations

Provide an image and describe what should change and what should stay the same. The agent can use chat attachments, Knowledge images it can access, run files available to the current run, or public HTTPS image URLs allowed by the workspace's network policy.

Make three variations of the attached product image. Keep the product shape and label unchanged, and try a different background color in each version.

References must be single-frame PNG, JPEG, or WebP images. A call accepts up to 16 references, with limits of 20 MiB and 36 million pixels per image, and 40 MiB combined including any mask.

For a targeted edit, provide a PNG mask with an alpha channel and the same dimensions as the first reference. Transparent areas guide where to edit. Review the result: masks do not guarantee that every other pixel stays unchanged.

Create transparent assets

Ask for an isolated subject on a transparent background and choose PNG or WebP. The agent should set background to transparent as well as describe the transparent background in the prompt. JPEG cannot preserve transparency.

Create a cutout of a small orange delivery robot on a transparent background. Save it as a PNG for placing over presentation slides. Use background=transparent.

Avoid asking for a colored backdrop in the same request. Inspect the downloaded image before using it: a request for transparency does not guarantee that the entire background is transparent. The tool reports whether the saved file has an alpha channel and whether any pixels are actually transparent or translucent.

Find and reuse the images

Open Files created on the run or Run Files in the workspace to preview and download the results. The agent receives an artifact ID for each saved image and can use it as a reference for another edit in the same run.

To reuse an image in a later run, select it as an input file. Choose Add to Knowledge when you want an independent copy as reusable source material. For API workflows, see reuse an existing artifact.

If generation times out or saving fails, check Files created before asking for another attempt. Some images may already have been saved. The tool does not automatically repeat an uncertain request, which could duplicate generation and budget use.