| name | generate-media |
| description | Use this skill whenever you need to generate or edit images, or generate or extend videos using the generate_or_edit_media tool. Covers prompt engineering, parameter selection, reference image usage, and video generation/extension. Trigger when the user asks to create, generate, edit, modify, or extend any image or video asset. |
| category | Data & Media |
| tags | image, video, generation, editing, gemini, veo |
| compatibility | Requires the generate_or_edit_media tool and a Google BYOK key. |
generate_or_edit_media Tool Guide
Tool Parameters
| Parameter | Type | Required | Description |
|---|
type | "image" or "video" | Yes | Whether to generate an image or video |
prompt | string (min 3 chars) | Yes | The generation/edit prompt |
reference_images | string[] (max 8) | No | Paths or URLs to reference images. Mutually exclusive with reference_video |
image_reference_mode | "reference_generate" or "edit" | No | Image-only. reference_generate (default) creates a new image inspired by references. edit directly transforms a referenced image |
reference_video | string | No | Video extension only. Use the real sandboxPath from a prior generate_or_edit_media video result (e.g. .cheatcode/assets/videos/...mp4), or an HTTPS URL to that file. Mutually exclusive with reference_images |
aspect_ratio | string | No | Image: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9. Video: 16:9 (default) or 9:16 |
duration | 4, 6, or 8 | No | Video only. Length in seconds |
Underlying Models
- Images: Gemini 3.1 Flash Image (
gemini-3.1-flash-image)
- Videos: Veo 3.1 (
veo-3.1-generate-preview) — generates at 1080p with native audio
Decision Tree
1. Image or video?
- Static visual asset →
type: "image"
- Motion, animation, cinematic clip, anything with audio →
type: "video"
2. Generate or edit?
- No reference images → Pure generation (just
prompt)
- Reference images for style/mood/composition guidance → Set
reference_images, leave image_reference_mode unset (defaults to reference_generate)
- Directly transforming an existing image (inpainting, object removal, style transfer on the image itself) → Set
reference_images + image_reference_mode: "edit"
- Extending a prior generated video → Set
reference_video to the prior result's sandboxPath (under .cheatcode/assets/videos/). Do NOT combine with reference_images
3. Aspect ratio
Pick the ratio that fits the intended use:
| Use case | Recommended ratio |
|---|
| Square social post, avatar, icon | 1:1 |
| Instagram story, mobile portrait video | 9:16 |
| YouTube thumbnail, desktop hero, landscape video | 16:9 |
| Product photo (portrait) | 4:5 or 3:4 |
| Ultra-wide banner | 21:9 |
| Standard photo landscape | 3:2 |
Writing Effective Prompts
Prompt Structure
Order your prompt: scene/backdrop → subject → key details → style → constraints.
For Photorealistic Images
Use photography language: camera angles, lens types, lighting, and fine details.
A photorealistic close-up portrait of an elderly Japanese ceramicist in a
dimly lit workshop, hands shaping wet clay on a pottery wheel. Warm side
lighting from a single window, shallow depth of field with a 85mm f/1.4
lens. Weathered hands with clay residue, focused expression. 3:2 landscape.
For Stylized Illustrations and Stickers
Be explicit about the art style and background.
A kawaii-style sticker of a happy red panda holding a bubble tea, pastel
color palette with soft pink and mint green, clean bold outlines, flat
shading, white background.
For Text in Images
Gemini excels at rendering text. Be explicit about the text content, style, and placement. For tricky words, spell them letter-by-letter.
Create a modern minimalist logo for a coffee shop with the text "The Daily
Grind" in a clean sans-serif font. Earthy brown and cream color scheme,
centered composition on white background.
For Product Mockups
Describe the product, materials, lighting setup, and camera angle.
A high-resolution studio-lit product photograph of a minimalist ceramic
coffee mug on a light marble surface. Three-point softbox lighting for even
illumination, slight three-quarter angle, ultra-realistic with sharp focus
on the matte texture. No logos, no text, no watermark.
For Video Prompts
Include subject, action, style, camera motion, and audio cues.
A cinematic tracking shot of a woman walking through a rain-soaked Tokyo
street at night, neon reflections on wet pavement. She opens an umbrella as
thunder rumbles in the distance. Slow dolly forward, shallow depth of field,
moody blue-orange color grading.
Prompting for Video Audio
Veo 3.1 natively generates audio. Provide cues for dialogue, sound effects, and ambiance:
- Dialogue: Use quotes.
"This must be the key," he murmured.
- Sound effects: Describe explicitly.
Tires screeching loudly, engine roaring.
- Ambient noise: Describe the soundscape.
A faint hum resonates in the background, birds chirping.
Editing Images
Adding/Removing Elements
Provide the image via reference_images and set image_reference_mode: "edit".
prompt: "Using the provided image, add a small knitted wizard hat on the cat's head. Match the original lighting and style."
reference_images: ["/path/to/cat-photo.png"]
image_reference_mode: "edit"
Inpainting (Semantic Masking)
Conversationally define a mask — no explicit mask file needed.
prompt: "Change only the blue sofa to a vintage brown leather chesterfield sofa. Keep everything else exactly the same."
reference_images: ["/path/to/living-room.png"]
image_reference_mode: "edit"
Style Transfer
Provide the style reference and describe the transformation.
prompt: "Transform this photograph into a watercolor painting style. Preserve the original composition but render with visible brushstrokes and soft color bleeding."
reference_images: ["/path/to/photo.jpg"]
image_reference_mode: "edit"
Compositing Multiple Images
Provide multiple references and describe how they combine.
prompt: "Create a professional e-commerce fashion photo. Place the dress from the first image on the model from the second image. Match lighting and perspective."
reference_images: ["/path/to/dress.png", "/path/to/model.png"]
image_reference_mode: "reference_generate"
Video-Specific Features
Image-to-Video
Generate an image first, then use it as the starting frame.
type: "video"
prompt: "Panning wide shot of this calico kitten waking up and stretching in warm sunshine"
reference_images: ["/path/to/kitten-image.png"]
Video Extension
Extend a video you already generated with this tool. Copy sandboxPath from that run's JSON output — do not invent or guess a URI.
type: "video"
prompt: "The butterfly lands gently on an orange flower as a puppy runs up"
reference_video: ".cheatcode/assets/videos/a-fluffy-orange-tabby-cat-sitting-on-a-sunny-win-50ad8b35.mp4"
duration: 8
Where to get reference_video:
- Always prefer the
sandboxPath field from the previous generate_or_edit_media result (paths look like .cheatcode/assets/videos/<slug>-<hash>.mp4).
- A public HTTPS URL to the same file also works when you have one.
- Do not use placeholder examples, Vertex operation IDs, or
projects/.../operations/... strings unless that exact value was returned by a prior tool call on your stack.
Constraints for video extension:
- Source must be a video this tool (or a compatible prior generation) already produced — not an arbitrary upload unless readable at the path/URL you provide
- Maximum input length: 141 seconds
- Cannot combine
reference_video with reference_images
Reference Images for Video
Veo supports up to 3 reference images to guide video content (character appearance, product identity).
type: "video"
prompt: "A woman in a flamingo feather dress walks through shallow turquoise lagoon water. Cinematic, dreamlike atmosphere."
reference_images: ["/path/to/dress.png", "/path/to/woman.png", "/path/to/sunglasses.png"]
Important: Video reference images are capped at 3 (unlike images which allow up to 8).
Best Practices
- Be specific over generic: Instead of "fantasy armor," write "ornate elven plate armor, etched with silver leaf patterns, with a high collar and pauldrons shaped like falcon wings."
- State intent: "Create a logo for a high-end minimalist skincare brand" beats "Create a logo."
- Iterate with single changes: Don't rewrite the whole prompt. Follow up with "Keep everything the same, but make the lighting warmer."
- Use step-by-step for complex scenes: "First, a misty forest at dawn. Then, a moss-covered stone altar in the foreground. Finally, a glowing sword on the altar."
- Positive framing over negation: Instead of "no cars," write "an empty, deserted street with no signs of traffic."
- Camera language for composition: Use terms like
wide-angle shot, macro shot, low-angle perspective, dolly shot, aerial view.
- For edits, state invariants explicitly: "Change only the background; keep the product, edges, and shadows unchanged."
- Re-state invariants on each iteration: Gemini can drift on follow-ups; repeat what must stay the same.
Common Mistakes
- Setting
image_reference_mode: "edit" when you just want style inspiration (use default reference_generate instead)
- Providing
reference_images alongside reference_video (mutually exclusive)
- Using placeholder or made-up
reference_video values (e.g. projects/xxx/.../operations/xxx) instead of the actual sandboxPath from the last video result
- Pointing
reference_video at a path that does not exist in the sandbox (read the path from the tool output; do not fabricate it)
- Providing too many references for video (max 3 for video, max 8 for images)
- Using
duration for image generation (video-only parameter)
- Forgetting to specify
type — always required
