Generating Video

Generate video from a prompt or animate a reference image.

The generateVideo() function creates short video clips from a text prompt (and an optional reference image) using Google's Veo models. It returns a file object pointing at the generated MP4.

Veo runs as a long-running job; generateVideo() blocks until the clip is ready, then writes it to the VFS — so a single call gives you a finished file.

Basic Video Generation

let clip = generateVideo(
  prompt: "A slow cinematic drone shot flying over a misty mountain range at sunrise",
  model: "cinematic-video"
)

"Saved clip: {{clip}}"

Aspect Ratio, Duration, and Resolution

let portrait = generateVideo(
  prompt: "A neon hologram of a cat skateboarding through a city at night",
  model: "cinematic-video",
  aspectRatio: "9:16",
  durationSeconds: 6,
  resolution: "720p",
  filename: "cat-skate.mp4"
)

Image-to-Video

Pass an existing image file as inputImage to animate it (image-to-video):

let still = generateImage(
  prompt: "A lighthouse on a cliff, oil painting",
  filename: "lighthouse.png"
)

let animated = generateVideo(
  prompt: "Gentle waves crash against the cliff; the lighthouse beam sweeps slowly",
  inputImage: still,
  model: "cinematic-video",
  filename: "lighthouse.mp4"
)

Parameters

ParameterTypeDescription
promptstringRequired. What the video should show.
modelstringLogical video alias configured in the session tool manifest.
aspectRatiostring"16:9" (landscape) or "9:16" (portrait).
durationSecondsnumberClip length in seconds (provider-dependent bounds).
resolutionstring"720p" or "1080p" (provider-dependent).
inputImagefileOptional reference image (a file var) for image-to-video.
filenamestringOptional VFS path. Defaults to <uuid>.mp4.
cacheKeystringOptional manual cache key (template-interpolated).
forceCacheMissbooleanSkip the cache lookup but still persist the result.
retrynumberAdditional attempts on transient failure (0 = no retry).

Video generation is slow and costly, so results are cached aggressively across the exact resolved binding revision, alias, prompt/manual key, settings, and reference-image digest. A re-run with unchanged inputs returns the cached clip instantly. For tests, bind an alias to the scripted Rust media provider.

Deployment configuration maps the logical alias to a Veo upstream model, endpoint, credential environment source, byte limits, and exact permitted download origins. Credentials and provider model IDs are not embedded in the Kaya program.

Next Steps