Generate AI media (image or animation)
generate_mediaGenerate an AI image or a canvas-code-based animation directly into a clip.
kind="image": text-to-image. Pass
prompt. Optional:animation_setting(entry/exit — set it HERE, see below),style_id(from find type='image_gen_style_packs'),reference_image_urlormcp_upload_idfor image-to-image grounding.kind="animation": canvas-code animation rendered from a prompt. Pass
prompt. Optional:voiceover_text(drives timing),base_component_id(reuse a saved animation as the starting point),reference_image_urlormcp_upload_idfor visual grounding.
Generation is asynchronous: the element is created immediately with a stable element_id and rendered in the background. Poll get_clip(select:['busy']): an EMPTY busy means the render has landed. (This previously said to watch the phantom flag; phantom has never been a key get_clip returns, so there was nothing to poll.)
Set presentation up front. animation_setting is applied to the element as it is created, so the image enters correctly the first time it renders. Doing it afterwards with update_elements means writing to the element that is still generating, which is the write most likely to be refused while the generation holds it.
group is NOT accepted here, unlike add_elements: a generated element is built in the background, and the grouping would be overwritten when the render lands. Add it ungrouped, then call update_elements with group once it appears.
TIMING: images land in seconds; animations take tens of seconds to a few minutes. Poll get_clip(select:['busy']) until busy is empty. A slow animation is still rendering, not stuck: do not call generate_media again for it, because each call is a new generation and uses credits again.
Tip: use this tool whenever the user asks for a "generated", "AI", or "create me a" visual. For uploaded photos / logos / icons / GIFs, use add_elements with element_type='image' and a src or mcp_upload_id instead.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"kind": "<kind>",
"project_id": "<project_id>",
"clip_id": "<clip_id>",
"prompt": "<prompt>",
"x": "<x>",
"y": "<y>",
"width": "<width>",
"height": "<height>"
},
"name": "generate_media"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | Top-left X in canvas pixels. | |
| y | Yes | Top-left Y in canvas pixels. | |
| kind | Yes | 'image' = AI text-to-image; 'animation' = canvas-code-based motion graphic. | |
| model | No | Image only. Default `gemini-3-pro-image` (Nano Banana Pro; usually leave it). Faster/cheaper: `gemini-3.1-flash-image`, `gemini-nano-banana-2.1` (newest), `gemini-3.1-flash-lite-image` (cheapest), `gemini-2.5-flash-image`. `gpt-image-2.5-flare` (fast), `gpt-image-2.5-sunburst` (precise edits), `gpt-image-2` (legible text, several reference images). `gpt-image-1` / `gpt-image-1.5`: square-ish only, a wide box snaps to 4:3 (not for banners). | |
| width | Yes | Width in pixels. | |
| height | Yes | Height in pixels. | |
| prompt | Yes | Generation prompt. For animations, be SPECIFIC: name the UI elements, interaction sequence, timing feel, and visual style. Vague prompts produce bad output. | |
| clip_id | Yes | Clip ID to place the generated element into. | |
| end_time | No | Disappear at (seconds). | |
| style_id | No | Image only. Style preset ID from find(type='image_gen_style_packs'). See resource clueso://docs/generation-styles. | |
| background | No | Image only. `false` = transparent cut-out (icons, logos, stickers). Honoured ONLY with `model` set in the same call to `gpt-image-2.5-flare` (default pick), `gpt-image-2.5-sunburst`, `gpt-image-1` or `gpt-image-1.5`; other models are always opaque. Asking for transparency in the prompt paints a checkerboard as real pixels. | |
| project_id | Yes | Project ID. | |
| start_time | No | Appear at (seconds). | |
| aspect_ratio | No | Image only. Overrides the ratio inferred from width/height (usually leave it; set when the box is a placeholder). Clamped per model: gpt-image-1/1.5 only 1:1, 4:3, 3:4; gpt-image-2.5 pair adds 16:9, 9:16; gpt-image-2 has no 3:2 or 2:3 (→ 4:3, 3:4). Not reported back. | |
| mcp_upload_id | No | mcp_upload_id from upload_file, or a Clueso upload_id. Resolved server-side to a presigned URL before generation. | |
| voiceover_text | No | Animation only. Paces the motion to the spoken script — and as a side effect sets this clip's voiceover text and triggers speech generation for the clip. If the clip's current voiceover_text (get_clip) has <SYNC_MARKER N> tokens, this text must carry each of them once, in order, or the animation is refused. | |
| animation_setting | No | Image only. Entry/exit animation, same shape as add_elements' type_data.animation_setting. The design guide asks AI images to enter with `masked_reveal` or a slow fade, so set it here rather than following up with update_elements — that follow-up targets the element while it is still generating. Ignored for kind='animation', which animates through its generated code. | |
| base_component_id | No | Animation only. Reuse a saved animation component as the starting point (from find(type='element_components')). To re-skin its tunable parameters, set parameter_values via update_elements after it renders. | |
| reference_image_url | No | Public URL of a reference image. Mutually exclusive with mcp_upload_id. |