Skip to main content
POST
Generate a video

Authorizations

Authorization
string
header
required

An organization API key created in Settings → Team, sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string | null

Reuse the same value when retrying the same request; a repeat returns the original generation without charging again. Reusing it with a different body returns 409.

Maximum string length: 128

Body

application/json

Generate a video. The same endpoint covers text-, image- and reference-driven generation, video extension (source_generation_id) and motion control (a motion-control model with character_image and motion_video). GET /v1/models/{id} lists which inputs each mode needs.

aspect_ratio
string | null

Requested aspect ratio (e.g. 16:9)

audio
string | null

Asset id from POST /v1/uploads or a generation output's asset_id. Audio file URL for audio-to-video models like Wan 2.2 InfiniteTalk

audio_duration_seconds
number | null

Audio duration in seconds for per-second credit calculation (Wan 2.2 InfiniteTalk)

cfg_scale
number | null

Kling V3/O3 CFG scale (0-1) controlling prompt adherence

character_id
integer
default:0

When image has multiple people, select which character (0 = leftmost)

Required range: 0 <= x <= 10
character_image
string | null

Asset id from POST /v1/uploads or a generation output's asset_id. URL of the character/avatar image whose appearance will be preserved. Character must have clear body proportions, no occlusion, and occupy >5% of image area.

character_orientation
string
default:image

'image' (match person orientation, max 10s output) or 'video' (match reference video orientation, max 30s output)

compression
number | null

Topaz Precision compression-artifact removal, 0-1

duration_seconds
integer | null

Requested duration seconds (5-8 for veo-2)

element_images
string[] | null

Asset id from POST /v1/uploads or a generation output's asset_id. List of image URLs for Kling multi-image video generation

elements
Elements · object[] | null

Kling V3/O3 elements (characters/objects) to reference as @Element1, @Element2

enhancement_model
string | null

Topaz enhancement model (e.g. 'Proteus', 'Starlight Precise 2.6')

Maximum string length: 64
face_image
string | null

Asset id from POST /v1/uploads or a generation output's asset_id. Face image URL for talking avatar models like Wan 2.2 InfiniteTalk

first_frame
string | null

Asset id from POST /v1/uploads or a generation output's asset_id. First frame URL for video generation based on start/end frames

frames_per_second
integer | null

Wan output frame rate

Required range: 4 <= x <= 60
generate_audio
boolean | null

Enable audio generation for Veo 3+ models (default: true for Veo 3+)

grain
number | null

Topaz Precision film grain, 0-0.1

halo
number | null

Topaz Precision halo reduction, 0-1

idempotency_key
string | null

Client-supplied non-whitespace key (1-128 chars); an identical retry returns the original generation without re-charging

Required string length: 1 - 128
Pattern: ^\S+$
keep_audio
boolean | null

Preserve source-video audio in Kling O3 video-to-video modes

keep_original_sound
boolean
default:false

Preserve audio from the reference video

keyframes
Keyframe · object[] | null

Asset id from POST /v1/uploads or a generation output's asset_id. FLUX.3 keyframes with exact 24 fps timeline positions

last_frame
string | null

Asset id from POST /v1/uploads or a generation output's asset_id. Last frame URL for video generation based on start/end frames

mode
string | null

Generation mode id declared by a matrix video model

model
string | null

Video model identifier (veo-3.1-generate-001, wan-2.2-infinitetalk-fal, etc.)

motion_video
string | null

Asset id from POST /v1/uploads or a generation output's asset_id. URL of the reference video containing the motion to transfer. Must show realistic character with entire/upper body visible including head, without obstruction.

multi_prompt
Multi Prompt · object[] | null

Kling V3/O3 multi-shot prompts; list of {prompt, duration} shots

negative_prompt
string | null

Optional negative prompt

noise
number | null

Topaz Precision noise reduction, 0-1

num_frames
integer | null

Wan output frame count

Required range: 40 <= x <= 120Must be a multiple of 4
previous_interaction_id
string | null

Gemini Omni Flash only: chain this generation onto a previous Omni interaction (result_meta.interaction_id) for conversational video editing

Maximum string length: 256
project_id
string | null

Project scope for the generated asset (optional)

prompt
string
default:""

Text prompt for video generation (optional for audio-to-video models like Wan 2.2)

quality
string | null

Video quality setting (high, medium, low, std, pro)

recover_detail
number | null

Topaz Precision original-detail recovery, 0-1

reference_audios
string[] | null

Asset id from POST /v1/uploads or a generation output's asset_id. Reference audio URLs; model-specific limits and visual-reference requirements come from the video catalog

reference_image
string | null

Asset id from POST /v1/uploads or a generation output's asset_id. Single reference image URL for Kling reference tab

reference_images
string[] | null

Asset id from POST /v1/uploads or a generation output's asset_id. List of reference image URLs for image-to-video generation

reference_names
Reference Names · object | null

User-facing aliases for Seedance references, keyed by reference_images/reference_videos/reference_audios

reference_videos
string[] | null

Asset id from POST /v1/uploads or a generation output's asset_id. Reference video URLs; model-specific limits come from the video catalog

resolution
enum<string> | null

Wan output resolution

Available options:
480p,
580p,
720p
shot_type
string | null

Kling V3/O3 multi-shot structure: 'customize' or 'intelligent'

softness
number | null

Topaz Starlight Precise 2.6 softness, 1 (sharpest) to 5 (softest)

source_generation_id
string | null

Completed source video generation id (same value as get_generation.generation_id)

source_video
string | null

Asset id from POST /v1/uploads or a generation output's asset_id. Source/reference video URL for Kling O3 edit/restyle modes

tier
string | null

Quality or resolution tier id declared by a matrix video model

variant
string | null

Speed/quality variant declared by the model's variant parameter (e.g. P-Video 2 Pro: speed, quality, cost); priced by the model's credit matrix

Maximum string length: 64

Response

Successful Response

One generation. Poll GET /v1/generations/{id} until status is completed or failed.

created_at
string<date-time>
required
id
string
required
Example:

"6f1c2d3e-9a0b-4c7d-8e1f-2a3b4c5d6e7f"

model
string
required
Example:

"seedance-2-5-fal"

prompt
string
required
status
enum<string>
required
Available options:
pending,
completed,
failed
type
enum<string>
required
Available options:
image,
video,
audio
completed_at
string<date-time> | null
credits_charged
number | null

Credits actually charged; null while pending.

error
GenerationError · object | null
idempotency_key
string | null
outputs
GenerationOutput · object[]