Generate a standalone image from a text prompt, or edit/restyle images supplied as references.
**When to use:**
Use this tool based on the requested output, not assumed model limitations such as an inability
to render text.
If the user explicitly asks for an image, picture, photo, illustration, artwork, sticker, icon,
graphic, or 2d vector, use this tool. The explicitly named output takes priority over
design-like content within it, including text, statistics, labels, callouts, or an
infographic-like composition. For example, "create an image about coffee with bold stat
callouts" uses generate-image.
Use create-design when the requested output itself is an editable Canva page or layout, such as
"create an infographic". "Create an image of an infographic" still uses generate-image. The
verb "create" or "design" alone does not make the request a Canva design.
**When not to use:**
Do not use when the requested output itself is a designed page or layout, such as an
infographic, poster, wallpaper, flyer, presentation, or social media post; use create-design.
To add, position, resize, or replace content inside an existing design, use the design-editing
workflow instead; the image is source media and the design page is the edit target.
**Image references and attachments:**
For image-to-image generation or editing, add one MEDIA entry to imageReferences for every
reference image. Pass the ID of an existing Canva MEDIA content reference directly.
Before using a user-provided attachment as a reference, upload it to Canva: call
create-upload-url, then send the attachment's raw bytes to the returned upload URL exactly as
instructed. Each upload URL is single-use, so call create-upload-url separately for every
attachment. Wait for every upload to succeed, then use the mediaId from each upload response as
a separate MEDIA entry in imageReferences. For example, after uploading two attachments
(replace the illustrative IDs with their returned mediaIds):
```json
{
"prompt": "Restyle both reference images as watercolor illustrations",
"imageReferences": [
{"type": "MEDIA", "id": "MAAAAAAAAAAA"},
{"type": "MEDIA", "id": "MBBBBBBBBBBB"}
]
}
```
Use exactly one imageReferences entry per successfully uploaded attachment. Never combine
multiple media IDs into one string or object, and never put an upload URL in imageReferences.
Do not pass assistant-hosted attachment URLs directly to this tool. If any attachment cannot be
uploaded, do not silently omit it; explain the failure to the user.
Omit imageReferences for pure text-to-image generation.
**Result:**
This call returns only a jobId, not the finished image. When this tool's UI widget is shown, the
widget polls get-generate-image-job itself and displays the image when ready - do not poll it
yourself. Only when no widget is shown, pass the jobId to get-generate-image-job and keep checking
until the job succeeds or fails.