Generate Image
generate-imageGenerate 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):
{
"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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The user's request for the image, copied exactly as they wrote it. Do not add, remove or rephrase anything; put your own summary in user_intent. Only reword when the user asks for the prompt to be rewritten or refined. If the request was gathered over several messages, join the user's own words from those messages in order, including any options they chose. Example. User: "Can you do a picture of our new bakery's front window at sunrise with a chalk sign that says Open 7am" prompt: "Can you do a picture of our new bakery's front window at sunrise with a chalk sign that says Open 7am" | |
| aspectRatio | No | Desired output aspect ratio, applied on a best-effort basis. When editing a previously generated image, reuse the exact `aspectRatio` enum value used to generate that image if that value is present in prior conversation or tool-call context, unless the user explicitly requests a different ratio. If the prior enum value is unavailable, omit this argument. For a new image without an explicit ratio, omit this argument. Do not retry solely if the returned image does not exactly match the requested ratio. When provided, `aspectRatio` must be exactly one of the enum values listed below. Translate the user's request into the matching enum value; for example, for `1:1`, send `SQUARE_1_1`. Never send a raw ratio such as `1:1` or a descriptive word such as `square`. If the user provides both an explicit numeric ratio and conflicting descriptive wording, use the numeric ratio to choose the enum value. - `SQUARE_1_1`: Use for "square" or "1:1". - `LANDSCAPE_16_9`: Use for "landscape", "wide", "widescreen", or "16:9". - `LANDSCAPE_5_4`: Use for an explicit "5:4". - `LANDSCAPE_4_3`: Use for an explicit "4:3". - `LANDSCAPE_3_2`: Use for an explicit "3:2". - `LANDSCAPE_2_1`: Use for an explicit "2:1", "panoramic", or "ultra-wide". - `PORTRAIT_9_16`: Use for "portrait", "tall", "vertical", or "9:16". - `PORTRAIT_4_5`: Use for an explicit "4:5". - `PORTRAIT_3_4`: Use for an explicit "3:4". - `PORTRAIT_2_3`: Use for an explicit "2:3". - `PORTRAIT_1_2`: Use for an explicit "1:2". | |
| user_intent | No | Mandatory description of what the user is trying to accomplish with this tool call. This should always be provided by LLM clients. Please keep it concise (255 characters or less recommended). | |
| imageReferences | No | Optional source images to guide generation, such as for image editing. Each must be a MEDIA content reference. For a GeneratedImageResult, reference its media_id, never its design_id or applied_page_id. Omit for pure text-to-image generation. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Identifies the job this call started. Pass it to the companion poll tool to check on the job. |