Generate a video
generate_videoGenerate a video from a prompt, animate an existing image asset with referenceAssetId, continue a shot from the frame where the film cuts out of it with startFrame, land on a planned picture with endFrame, or put the people, products and places of up to 5 pictures into a new shot with references (read builtin-generative-video first). The shots of one story are made one after another, each from the frame where the one before it is cut, so the story moves forward. Duration is 4–15 seconds. The video comes with its own sound (generateAudio null or true) unless generateAudio is false. Standard settings: 5 seconds, 16:9, 720p, standard quality, with sound. quality picks how it is made: standard (null) for B-roll and most shots; high for a hero shot, made 5 to 15 seconds long and always with its own sound; highest only when the person asks for the best quality. A video with references is made at high, whatever quality you pick. One with endFrame is made at high with its own sound; silent, it costs about 29 credits a second at standard and about 68 credits a second at high. For a shot that must look filmed by a person (phone footage, a vlog, home video, found footage), read builtin-handheld-footage first. A request a quality cannot make, such as a silent video at high, runs at the next quality up and is charged at it. It answers at once with a Job ID and the media is made in the background: start every generation you need, keep working, then call wait_for_jobs with all their Job IDs to get each Asset ID for patch_film. Uses credits for each second: standard about 15 credits a second at 720p and about 9.7 credits a second at 480p; high about 29 credits a second at 720p and about 24 credits a second at 480p; highest about 113 credits a second at 720p and about 52 credits a second at 480p. So a 5-second 720p video uses 73 credits at standard, 146 at high and 563 at highest. Tell the person this estimate for the quality and length you picked before you generate. A credit refusal says what the video needs and how many credits are left: retry only with a duration, resolution or quality that fits, and never substitute another media kind.
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": {
"prompt": "<prompt>",
"durationSeconds": "<durationSeconds>",
"aspectRatio": "<aspectRatio>",
"resolution": "<resolution>",
"generateAudio": "<generateAudio>",
"referenceAssetId": "<referenceAssetId>",
"quality": "<quality>",
"startFrame": "<startFrame>",
"endFrame": "<endFrame>",
"references": "<references>",
"projectId": "<projectId>"
},
"name": "generate_video"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Up to 2000 characters. | |
| quality | Yes | standard (null) for B-roll and most shots, high for a hero shot, highest only when the person asks for the best quality. | |
| endFrame | Yes | The picture the video ends on, as asset:ID (an image asset) or asset:ID#t=6.4 (the frame of a video asset), or null. Needs referenceAssetId or startFrame. Use it when a shot must land on a planned picture: the opening of the next scene, or the film's first frame so the end loops into the start. With sound it runs at high quality. Silent (generateAudio false) it is a join between two shots: standard (null) makes it in about a minute, 5 seconds long at 720p, and high makes a larger picture in about five minutes, 4 to 15 seconds long. | |
| projectId | Yes | The project this call runs on without changing the open project. null (or leaving it out) uses the open project. wait_for_jobs takes the projectId of the calls that started the jobs. | |
| references | Yes | Up to 5 pictures of the people, products, places or look to keep in the video, in this order, or null for none. Each one is: asset:ID, an image asset; asset:ID#t=14.6, the frame of a video asset at 14.6 seconds; film:#t=3.2, the frame of the edit at 3.2 seconds. In the prompt call them Image 1 to Image 5 by their order: "Image 1 is the woman, Image 2 is her sneaker. She laces up the sneaker on a rooftop at sunset." Not with referenceAssetId, startFrame or endFrame: to open on a picture, put it here and say so in the prompt. | |
| resolution | Yes | ||
| startFrame | Yes | The frame of a video asset the video opens on, as asset:ID#t=6.4 (the frame at 6.4 seconds), or null. To make the next shot of a story, pass the frame of the shot before it where the film cuts out of it: the new shot starts exactly where that one ends, so the story goes on and never starts over. Not with referenceAssetId or references. | |
| aspectRatio | Yes | ||
| generateAudio | Yes | Whether the video has its own sound, made with the picture: dialogue, sound effects, ambience and music that match what happens. null or true (the default) makes sound. false makes the video silent: only when the person asks for a silent video. To keep a clip quiet under narration or music, keep its sound and set the clip's volume in the film instead: a silent video cannot get sound back. | |
| durationSeconds | Yes | ||
| referenceAssetId | Yes | An image asset id from search_assets that the video opens on, or null. The opening shot of a story only: a later shot opens where the shot before it ends (startFrame), never on this picture again. |