Generate Video
xbrush_video_generateGenerate AI videos from an image, text prompt, or reference images. Starts an async job, returning a request_id to poll for completion.
Instructions
Generate a video from a start image, a text prompt, and/or reference images (reference-to-video). Submits async — poll the returned request_id with xbrush_get_request (typical wait 2-10 min).
Args: model (string, required): Video model ID (e.g. kling-v3-pro, kling-o3, veo3.1, seedance-2.0, hailuo-02-pro, wan-2.7-video). Use xbrush_list_models(category='video') — entries include per-model duration constraints. image_url (string, optional): Start image (first frame) for image-to-video. Not needed for text-to-video or reference-to-video. image_urls (array, optional): Reference images for reference-to-video models (seedance-2.0/-fast). Each item is a URL string OR an object {url, role} where role is first_frame/last_frame/reference_image — so one call can combine a start frame, an end frame, and subject references. NUMBERING: in prompt/idea, @ImageN = the N-th item here by 1-based ARRAY POSITION, counting first_frame/last_frame too (NOT 'the N-th reference'). E.g. [last_frame, reference_image] → the reference is @Image2. image_url is not required when this is set. prompt (string, optional): ENGLISH motion/action description, sent to the model as-is. Reference an image_urls item as @ImageN (N = its 1-based position in image_urls). Use 'idea' instead for non-English text. Provide prompt or idea for text-to-video. idea (string, optional): NON-English description (e.g. Korean) — the server translates it before generation. Use this instead of prompt when not writing in English. Reference an image_urls item as @ImageN (N = its 1-based position in image_urls). end_image_url (string, optional): End image (last frame), for models that support an end frame. duration (int, optional): Seconds; valid range is model-specific (e.g. seedance-2.0 4–15, kling 5/10, veo3 4–8). resolution (string, optional): Resolution tier for models that support it (seedance-2.0: 480p/720p/1080p/1440p/2160p/4k/512p/768p). Server-validated per model. aspect_ratio (string, optional): Aspect ratio for models that support it (seedance-2.0: auto/adaptive/16:9/9:16/1:1/4:3/3:4/21:9). generate_audio (bool, optional): Generate audio with the video (seedance-2.0/-fast). consistency_mode (string, optional): Reference consistency for reference-to-video (seedance-2.0/-fast): overlay/advanced/auto. prompt_relevance (float, optional): Prompt adherence (0.0-1.0).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| idea | No | Same purpose as prompt but for NON-English text (e.g. Korean): the server translates it before sending to the model. Use 'idea' for non-English, 'prompt' for English. Reference an image_urls entry as @ImageN, where N is its 1-based position in the image_urls array (first_frame/last_frame count toward the position too). Provide prompt OR idea. | |
| model | Yes | Video model to use (e.g. kling-v3-pro, kling-o3, veo3.1, seedance-2.0, hailuo-02-pro, wan-2.7-video). Use xbrush_list_models with category='video' to see options and per-model duration constraints. | |
| prompt | No | Motion/action description in ENGLISH — sent to the model as-is. Use this when writing directly in English; for any non-English text use 'idea' instead (the server translates it). Reference an image_urls entry as @ImageN, where N is its 1-based position in the image_urls array (first_frame/last_frame count toward the position too). Provide prompt OR idea (required for text-to-video when no image is supplied). | |
| duration | No | Video duration in seconds (integer). Valid range is model-specific — e.g. kling 5 or 10, veo3 4–8, seedance-2.0 4–15 (default 5), wan-2.7 2–15. Default depends on the model; out-of-range values are rejected by the server per model. | |
| image_url | No | URL of the start image (first frame) for image-to-video. Optional — text-to-video (prompt only) and reference-to-video (image_urls) models don't need it. The selected model decides what is required. | |
| image_urls | No | Reference images for reference-to-video models (e.g. seedance-2.0 / seedance-2.0-fast). Each element is EITHER a plain URL string OR an object {url, role} where role is 'first_frame' | 'last_frame' | 'reference_image'. The {url, role} form lets a single call combine a start frame, an end frame, and subject/style references in one list (passed through to the model as video_params.image_urls). Standalone: image_url is not required when this is set. NUMBERING (important): in prompt/idea, @Image1, @Image2, … refer to entries of THIS array by 1-based position in array order, counting EVERY entry — first_frame and last_frame included, NOT only reference_image entries. Example: image_urls=[{url, role:'last_frame'}, {url, role:'reference_image'}] → the reference is @Image2, because last_frame occupies position 1. To make a reference @Image1, place it first in the array. Ignored by models without a reference-image input. | |
| resolution | No | Output resolution tier for video models that support it (seedance-2.0/-fast: "480p", "720p", "1080p", "1440p", "2160p", "4k", "512p", "768p"). Server-validated per model; ignored by models that size differently. Higher tiers cost more. | |
| aspect_ratio | No | Aspect ratio for video models that support it (seedance-2.0/-fast: "auto", "adaptive", "16:9", "9:16", "1:1", "4:3", "3:4", "21:9"). Server-validated per model. | |
| end_image_url | No | URL of the end image (last frame). Creates a transition from start to end. Supported by select models (e.g. kling); ignored by models without an end-frame input such as seedance-2.0. | |
| generate_audio | No | Whether to generate audio together with the video (seedance-2.0/-fast). Default is model-specific. | |
| consistency_mode | No | Subject/reference consistency mode for reference-to-video models (seedance-2.0/-fast): "overlay", "advanced", or "auto". Controls how reference images stay consistent across frames. Server-validated; omit for the model default. | |
| prompt_relevance | No | How closely to follow the prompt (0.0-1.0). |