Skip to main content
POST
Create an AI video generation job

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string
required

Unique key for safe retries of job creation requests.

Required string length: 8 - 128

Body

application/json

Video generation request. The backend validates the (model_id, tier, resolution, duration_seconds, audio_enabled) tuple against the pricing matrix and rejects any invalid combo with 400 invalid_request. Call GET /v1/models/{model_id} for the authoritative options, or use the per-model matrix in the docs.

Required-in-practice fields beyond the OpenAPI required list: • mode — must be edit for V2V models or motion for MC models. • audio_enabled — required boolean for any model with audio pricing rows (Veo, Sora, Wan 2.6, Wan 2.7, V2V, MC, Kling, Seedance 1.5 Pro, Seedance 2.5, Seedance 2.5 V2V).

Orientation cheatsheet: • 9:16 → vertical / portrait (TikTok, Reels, Shorts) • 16:9 → horizontal / landscape (YouTube, web) • 1:1 → square (Instagram feed)

Models with inherit-from-input ratios (do NOT send ratio): wan-2.6, hailuo-2.3, grok-imagine-1.5, wan-2.6-v2v, kling-2.6-mc, kling-3.0-mc. minimax-h3 inherits only on the image-to-video path: send ratio for text-to-video, omit it when input_image_url is set (the output matches the input image).

Image-to-video-only models (input_image_url REQUIRED): wan-2.6, hailuo-2.3, grok-imagine-1.5.

model_id
enum<string>
required

Video model. Call GET /v1/models/{model_id} for full options.

Available options:
veo-3.1,
kling-2.6,
kling-3.0,
seedance-1.5-pro,
seedance-2.0,
seedance-2.5,
wan-2.6,
wan-2.7,
hailuo-2.3,
grok-imagine,
grok-imagine-1.5,
happyhorse-1.1,
kling-3.0-turbo,
gemini-omni,
sora-2,
sora-2-pro,
minimax-h3,
wan-2.6-v2v,
wan-2.7-videoedit,
seedance-2.5-v2v,
minimax-h3-v2v,
kling-2.6-mc,
kling-3.0-mc
prompt
string
required
Required string length: 1 - 4096
resolution
string
required

Per-model resolution: • veo-3.1 → 720p | 1080p | 4K • kling-2.6 → 1080p • kling-3.0 → 720p | 1080p • seedance-1.5-pro → 480p | 720p | 1080p • seedance-2.0 (tier=fast) → 480p | 720p • seedance-2.0 (tier=quality) → 480p | 720p | 1080p • seedance-2.5, seedance-2.5-v2v → 480p | 720p (no 1080p, no 4K) • wan-2.6, wan-2.7, wan-2.6-v2v, wan-2.7-videoedit → 720p | 1080p • hailuo-2.3 → 768p (6/10s) | 1080p (6s only) • minimax-h3, minimax-h3-v2v → 768p | 2K • grok-imagine → 480p | 720p • sora-2 → 720p • sora-2-pro → 720p | 1024x1792 | 1080x1920

duration_seconds
string
required

Duration as a STRING (not number). Per-model accepted values: • veo-3.1 → "8" (8s; extend for more) • kling-2.6 → "5" | "10" • kling-3.0 → "3" | "5" | "7" | "10" | "15" • seedance-1.5-pro → "4" | "8" | "12" • seedance-2.0 → "4" | "8" | "12" • seedance-2.5, seedance-2.5-v2v → "4" | "5" | "8" | "10" | "15" | "20" | "30" • wan-2.6 → "5" | "10" | "15" • wan-2.7 → "5" | "8" • wan-2.7-videoedit → "5" | "8" | "10" • wan-2.6-v2v → "5" | "10" • hailuo-2.3 (768p) → "6" | "10" • hailuo-2.3 (1080p) → "6" only • minimax-h3, minimax-h3-v2v → "4"–"15" (every integer) • grok-imagine → "6" | "10" | "15" | "20" | "30" • sora-2 / sora-2-pro → "4" | "8" | "12" | "16" | "20"

Example:

"8"

mode
enum<string>

• generate — text or first-frame image-to-video (most models). • edit — required for wan-2.6-v2v, wan-2.7-videoedit, seedance-2.5-v2v, minimax-h3-v2v (needs input_video_url). • motion — required for kling-2.6-mc, kling-3.0-mc (needs input_image_url + input_video_url).

Available options:
generate,
edit,
motion
tier
string

Per-model performance tier: • veo-3.1 → lite | fast | quality (default fast; lite cannot extend) • seedance-2.0 → fast | quality (fast has no 1080p) • hailuo-2.3 → standard | pro • grok-imagine → fun | normal | spicy (spicy rejects uploaded refs) Other models ignore this field.

ratio
string

Aspect ratio W:H. Per-model supported values: • veo-3.1, sora-2, sora-2-pro → 9:16, 16:9 • kling-2.6, kling-3.0 → 9:16, 16:9, 1:1 • seedance-1.5-pro, seedance-2.0 → 1:1, 4:3, 3:4, 16:9, 9:16, 21:9 (seedance-2.0 also: adaptive) • seedance-2.5, seedance-2.5-v2v → 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive • wan-2.7, wan-2.7-videoedit → 16:9, 9:16, 1:1, 4:3, 3:4 • grok-imagine → 2:3, 3:2, 1:1, 16:9, 9:16 • minimax-h3, minimax-h3-v2v → 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 (minimax-h3-v2v also: adaptive — its default; minimax-h3 REQUIRES ratio for text-to-video but ignores it when input_image_url is set — omit it for image-to-video) DO NOT send ratio for wan-2.6, hailuo-2.3, wan-2.6-v2v, kling-*-mc (ratio inherits from the input media).

Example:

"9:16"

audio_enabled
boolean

Per-model audio behavior: • forced-on (rejects false): veo-3.1, sora-2, sora-2-pro, wan-2.6, minimax-h3, minimax-h3-v2v (native stereo audio always on) • forced-off (rejects true): wan-2.7, hailuo-2.3, grok-imagine, wan-2.6-v2v, wan-2.7-videoedit, MC • toggle: kling-2.6, kling-3.0, seedance-1.5-pro, seedance-2.5, seedance-2.5-v2v • n/a (ignored): seedance-2.0

negative_prompt
string

Content to avoid. Supported by kling, seedance, wan, V2V, MC. Ignored by veo, sora, hailuo, grok.

input_image_url
string<uri>

Hosted image URL. REQUIRED for wan-2.6 / hailuo-2.3 (image-to-video) and for mode=motion (kling-*-mc). Optional first-frame for veo / kling / seedance / wan-2.7 / grok / sora. seedance-2.5 also accepts up to 4 reference images (never mixed with first/last frames). Use POST /v1/assets to host local files.

input_video_url
string<uri>

Hosted video URL. REQUIRED for mode=edit (wan-2.6-v2v, wan-2.7-videoedit, seedance-2.5-v2v, minimax-h3-v2v) and mode=motion (kling-*-mc). minimax-h3-v2v references must be MP4/MOV (H.264/H.265), ≤ 50 MB, 2–15s per clip, ≤ 15s total, and are billed on input + output seconds. Use POST /v1/assets to host local files.

Response

Video generation accepted.

id
string
required
object
enum<string>
required
Available options:
image_generation_job,
video_generation_job,
talking_avatar_job
status
enum<string>
required
Available options:
queued,
processing,
completed,
failed,
canceled
credits_reserved
integer
required
assets
object[]
required
created_at
string<date-time>
required
progress_percent
integer | null
Required range: 0 <= x <= 100
credits_used
integer | null
credits_refunded
integer
default:0
request
object
failure_code
string | null
failure_message
string | null
updated_at
string<date-time> | null
completed_at
string<date-time> | null
failed_at
string<date-time> | null