generate_video
Start a video generation: text-to-video (prompt only), image-to-video (image_url; add end_image_url for a first+last-frame clip), reference-to-video (image_urls / reference_video_urls on multi-reference models), lip-sync / talking photo (image_url + audio_url on lip-sync models), motion control (image_url + video_url on motion-control models — the driving video sets both the clip length and the cost: the server measures it and prices the call by its seconds, duration has no effect) or video edit / transform (video_url on video-edit models). Pick the model by capability in list_models; model-specific fields go in input (see get_model). The default model is tuned for quality and is not the cheapest one — compare reference prices in list_models. Returns request_id and cost in credits immediately — video renders take 1–10 minutes, poll with wait_generation.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "generate_video"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Fixes randomness. Only for models that declare seed (see get_model); a model known not to apply it rejects the call. Video renders one clip per call (no batch) — for multiple distinct variants run separate calls with a different idempotency_key each (or a different seed each where the model declares seed); identical calls within ~20s are de-duplicated to one generation. | |
| input | No | Model-specific parameters from get_model input_schema.parameters, keyed by parameter name and merged with the fields above — e.g. multi_shots, kling_elements, character_orientation. Some of them (e.g. sound, mode, speed, audio, multi_shots) change the cost of the call — get_model shows the reference pricing. A misspelled name, or a parameter this model is known not to apply, is rejected before the generation starts; the error lists the parameters the model declares. | |
| model | No | Model slug from list_models (slugs may contain '/', e.g. 'grok-imagine/text-to-video' — pass verbatim). Omit to use the default video model (text-to-video or image-to-video is picked automatically based on image_url). | |
| prompt | No | Scene description. English recommended for best quality. Do not include on-screen text. Required for text-to-video; optional when the call carries media input (lip-sync and motion-control models work without it). | |
| duration | No | Clip length in seconds — model-dependent (3–30; get_model lists the allowed values). Do not pass it to lip-sync and motion-control models: the server measures the audio / driving video and the clip follows its length, and a lip-sync model that does not declare duration rejects the call. With reference_video_urls it must be a whole number of seconds within the model range. | |
| audio_url | No | Public https URL of the speech audio (mp3/wav) for lip-sync / talking-photo models — the clip length follows the audio. | |
| image_url | No | Public https URL of the start frame — switches to image-to-video. Also the character/portrait photo for lip-sync and motion-control models. | |
| video_url | No | Public https URL of the source video: the driving motion clip for motion-control models (required there; 3–30 s, up to 10 s with character_orientation "image"; the result follows its length) or the clip to edit / transform for video-edit models. | |
| image_urls | No | Public https URLs of reference images (characters, products, style) for multi-reference / reference-to-video and video-edit models. | |
| resolution | No | e.g. '480p', '720p', '1080p', '4k'. Only for models that declare resolution (see get_model). | |
| aspect_ratio | No | e.g. '16:9', '9:16', '1:1', '4:3', '3:4', '21:9' (model-dependent). | |
| wait_seconds | No | Optional inline wait before returning. | |
| end_image_url | No | Public https URL of the LAST frame for first+last-frame clips; requires image_url. Works on every model that supports a last frame — the server maps this one field to the name the model reads. | |
| generate_audio | No | Generate a soundtrack/ambient audio. Only for models that declare an audio switch (see get_model); a model known not to apply it rejects the call. | |
| idempotency_key | No | Optional stable key (up to 255 characters) to safely retry without creating a duplicate generation. Reuse the same key only when retrying the same request: the same key with a different model or input is rejected with idempotency_key_reuse. | |
| negative_prompt | No | What to avoid. Only for models that declare negative_prompt (see get_model); a model known not to apply it rejects the call. | |
| reference_video_urls | No | Public https URLs of reference clips for reference-to-video models. The number of clips is model-dependent (get_model lists it as maxItems of reference_video_urls; e.g. 3 on Seedance 2, 10 on Seedance 2.5) — a call above the limit is rejected before any credits are reserved, clips are never dropped silently. The server measures each clip and adds its seconds to the cost — whole seconds rounded up, except that a tail of up to 0.1 s above a whole second is not counted (10.04 s counts as 10, 10.11 s as 11); durations sent by the client are ignored. |