Videos

Use video generation for ad concepts, product motion, visual hooks, editing existing clips, and motion-control workflows.

Endpoints

Method	Endpoint	Purpose
`POST`	`/v1/video-generations`	Create a video generation, edit, or motion-control job.
`GET`	`/v1/video-generations`	List recent video jobs.
`GET`	`/v1/video-generations/{job_id}`	Get one video job.
`POST`	`/v1/video-generations/{job_id}/extend`	Extend a supported completed video job.

Orientation cheatsheet

You want	Pass `ratio`
Vertical / portrait (TikTok, Reels, Shorts, Stories)	`"9:16"`
Horizontal / landscape (YouTube, web hero)	`"16:9"`
Square (Instagram feed)	`"1:1"`

For models that inherit the ratio from their input (wan-2.6, hailuo-2.3, grok-imagine-1.5, wan-2.6-v2v, kling-2.6-mc, kling-3.0-mc), omit ratio entirely and upload an input image / video that already has the orientation you want. minimax-h3 inherits only on the image-to-video path: send ratio for text-to-video, but omit it when input_image_url is set — the output matches the input image.

Create Parameters

A successful video request must carry a valid (model_id, resolution, duration_seconds, audio_enabled) tuple. The combos are model-specific — call GET /v1/models for the authoritative list, or use the per-model matrix below.

Field	Type	Required	Notes
`model_id`	string	Yes	One of the IDs listed in Models.
`prompt`	string	Yes	The video instruction. Max 4096 characters.
`mode`	string	Yes for edit/motion, optional otherwise	`generate` (default), `edit` (`wan-2.6-v2v`, `wan-2.7-videoedit`, `seedance-2.5-v2v`, `minimax-h3-v2v`), `motion` (`kling-2.6-mc`, `kling-3.0-mc`).
`resolution`	string	Yes (in practice)	Pricing fails without it. Allowed values are model-specific: `480p`, `720p`, `768p`, `1080p`, `2K`, `4K`, or Sora 2 Pro’s `1024x1792` / `1080x1920`.
`duration_seconds`	string	Yes (in practice)	String, not number. Must match the model’s supported durations (e.g. `"8"` for Veo, `"4"`/`"8"`/`"12"` for Seedance 1.5/2.0, up to `"30"` for Seedance 2.5).
`audio_enabled`	boolean	Yes for models with audio pricing	`true` for Veo / Sora / Wan 2.6 / MiniMax H3 (both ids — native stereo audio is always on), `false` for Wan 2.7 / V2V / motion-control, free toggle for Kling 2.6/3.0, Seedance 1.5 Pro and Seedance 2.5 / 2.5 V2V, ignored by Seedance 2.0 / Hailuo / Grok.
`tier`	string	No	`lite` / `fast` / `quality` (Veo), `fast` / `quality` (Seedance 2.0), `standard` / `pro` (Hailuo), `fun` / `normal` / `spicy` (Grok). Other models — including `grok-imagine-1.5`, `happyhorse-1.1`, `kling-3.0-turbo`, `gemini-omni`, `seedance-2.5`, `seedance-2.5-v2v` — ignore this.
`ratio`	string	Conditional	`9:16`, `16:9`, `1:1`, `4:3`, `3:4`, `21:9`, `adaptive` (model-dependent). Omit for ratio-inheriting models (`wan-2.6`, `hailuo-2.3`, `grok-imagine-1.5`, `wan-2.6-v2v`, `kling-2.6-mc`, `kling-3.0-mc`). `minimax-h3` requires it for text-to-video but ignores it when `input_image_url` is set — omit it for image-to-video. `adaptive` is the `minimax-h3-v2v` default.
`negative_prompt`	string	No	Content to avoid (forwarded for Kling, Seedance, Wan, V2V, MC).
`input_image_url`	string	Conditional	Required for `wan-2.6`, `hailuo-2.3`, `grok-imagine-1.5`, `kling-2.6-mc`, `kling-3.0-mc`. Optional first frame for Veo / Kling / Seedance / Wan 2.7 / Sora / Grok / MiniMax H3 (H3’s output matches the image — omit `ratio`). `seedance-2.5` also accepts up to 4 reference images (never mixed with first/last frames).
`input_video_url`	string	Conditional	Required for `mode=edit` and `mode=motion`. Upload local files via `POST /v1/assets` first.

Idempotency-Key is required on every POST /v1/video-generations. Reuse the same key only when retrying the exact same job.

Per-model valid combos

These are the exact tuples the pricing engine accepts. Sending anything else returns 400 invalid_request with message Invalid parameter combination for model ....

`model_id`	`mode`	`tier`	`resolution`	`duration_seconds`	`audio_enabled`
`veo-3.1`	`generate`	`lite` / `fast` / `quality`	`720p`, `1080p`, `4K`	`"8"`	`true`
`kling-2.6`	`generate`	—	`1080p`	`"5"`, `"10"`	`true` / `false`
`kling-3.0`	`generate`	—	`720p`, `1080p`	`"3"`, `"5"`, `"8"`, `"10"`, `"15"`	`true` / `false`
`seedance-1.5-pro`	`generate`	—	`480p`, `720p`, `1080p`	`"4"`, `"8"`, `"12"`	`true` / `false`
`seedance-2.0`	`generate`	`fast` / `quality`	`480p`, `720p`, `1080p` (quality only)	`"5"`, `"8"`, `"10"` (qual), `"15"`	ignored
`seedance-2.5`	`generate`	—	`480p`, `720p`	`"4"`, `"5"`, `"8"`, `"10"`, `"15"`, `"20"`, `"30"`	`true` / `false`
`wan-2.6`	`generate`	—	`720p`, `1080p`	`"5"`, `"10"`, `"15"`	`true`
`wan-2.7`	`generate`	—	`720p`, `1080p`	`"5"`, `"8"`, `"10"`, `"15"`	`false`
`hailuo-2.3`	`generate`	`standard` / `pro`	`768p`, `1080p` (6s only)	`"6"`, `"10"` (768p only)	ignored
`grok-imagine`	`generate`	`fun` / `normal` / `spicy`	`480p`, `720p`	`"6"`–`"30"`	ignored
`grok-imagine-1.5`	`generate`	—	`480p`, `720p`	`"6"`, `"8"`, `"10"`, `"15"`	ignored
`happyhorse-1.1`	`generate`	—	`720p`, `1080p`	`"5"`, `"8"`, `"10"`, `"15"`	ignored
`kling-3.0-turbo`	`generate`	—	`720p`, `1080p`	`"5"`, `"8"`, `"10"`, `"15"`	ignored
`gemini-omni`	`generate`	—	`720p`, `1080p`, `4K`	`"4"`, `"6"`, `"8"`, `"10"`	ignored
`sora-2`	`generate`	—	`720p`	`"4"`, `"8"`, `"12"`, `"16"`, `"20"`	`true`
`sora-2-pro`	`generate`	—	`720p`, `1024x1792`, `1080x1920`	`"4"`–`"20"` (model rules)	`true`
`minimax-h3`	`generate`	—	`768p`, `2K`	`"4"`–`"15"` (every integer)	`true`
`wan-2.6-v2v`	`edit`	—	`720p`, `1080p`	`"5"`, `"10"`	`false`
`wan-2.7-videoedit`	`edit`	—	`720p`, `1080p`	`"5"`, `"8"`, `"10"`	`false`
`seedance-2.5-v2v`	`edit`	—	`480p`, `720p`	`"4"`, `"5"`, `"8"`, `"10"`, `"15"`, `"20"`, `"30"`	`true` / `false`
`minimax-h3-v2v`	`edit`	—	`768p`, `2K`	`"4"`–`"15"` (every integer)	`true`

seedance-2.5-v2v credits depend on your input_video_url length as well as duration_seconds — the model is billed per second of input + output. credits = roundUpTo10( rate × ( min(ceil(reference_seconds), 30) + duration_seconds ) ), rate 8.5 at 480p and 19 at 720p. /v1/pricing lists the 30s-reference maximum; you are charged the measured amount, never more.minimax-h3-v2v is billed the same way: input + output seconds at 8 credits/s (768p) or 13 credits/s (2K), rounded up to the nearest 10. /v1/pricing lists the 15s-reference ceiling; shorter reference videos are charged on their measured duration. Reference videos must be MP4/MOV (H.264/H.265), ≤ 50 MB, 2–15s per clip, ≤ 15s total.

| kling-2.6-mc | motion | — | 720p, 1080p | "5", "10", "15", "30" | false | | kling-3.0-mc | motion | — | 720p, 1080p | "5", "10", "15", "30" | false |

Example: vertical Veo 3.1 ad (TikTok-style)

curl https://api.adskull.io/v1/video-generations \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: veo-vertical-001" \
  -d '{
    "mode": "generate",
    "model_id": "veo-3.1",
    "prompt": "Cinematic neon-lit skateboarder, slow-mo, bold colors",
    "ratio": "9:16",
    "resolution": "1080p",
    "duration_seconds": "8",
    "tier": "fast",
    "audio_enabled": true
  }'

Example: horizontal Kling 3.0 with audio toggle

curl https://api.adskull.io/v1/video-generations \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kling-horiz-001" \
  -d '{
    "mode": "generate",
    "model_id": "kling-3.0",
    "prompt": "Premium coffee bag rotating on a marble counter, morning light",
    "ratio": "16:9",
    "resolution": "1080p",
    "duration_seconds": "10",
    "audio_enabled": false
  }'

Example: 30-second single-pass Seedance 2.5

seedance-2.5 generates a full 30 seconds in one pass (no stitching). It caps at 720p — there is no 1080p or 4K option.

curl https://api.adskull.io/v1/video-generations \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seedance25-long-001" \
  -d '{
    "mode": "generate",
    "model_id": "seedance-2.5",
    "prompt": "Full product story: unboxing, close-up texture, lifestyle payoff",
    "ratio": "9:16",
    "resolution": "480p",
    "duration_seconds": "30",
    "audio_enabled": true
  }'

Example: image-to-video with Wan 2.6 (ratio inherits)

# 1) Upload your product image
curl https://api.adskull.io/v1/assets \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -F asset_type=image \
  -F file=@./product.png
# response: { "url": "https://cdn.adskull.io/uploads/..." }

# 2) Pass the hosted URL to the generation
curl https://api.adskull.io/v1/video-generations \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wan26-i2v-001" \
  -d '{
    "mode": "generate",
    "model_id": "wan-2.6",
    "prompt": "Smooth cinematic dolly-in on the bottle",
    "resolution": "1080p",
    "duration_seconds": "5",
    "audio_enabled": true,
    "input_image_url": "https://cdn.adskull.io/uploads/..."
  }'

Example: edit an existing video (Wan 2.6 V2V)

curl https://api.adskull.io/v1/video-generations \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: v2v-001" \
  -d '{
    "mode": "edit",
    "model_id": "wan-2.6-v2v",
    "prompt": "Add a snowfall ambient overlay and warmer color grade",
    "resolution": "720p",
    "duration_seconds": "5",
    "input_video_url": "https://cdn.adskull.io/uploads/source.mp4"
  }'

Example: motion control (Kling 3.0 MC)

curl https://api.adskull.io/v1/video-generations \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mc-001" \
  -d '{
    "mode": "motion",
    "model_id": "kling-3.0-mc",
    "prompt": "Apply the reference dance to the character",
    "input_image_url": "https://cdn.adskull.io/uploads/character.png",
    "input_video_url": "https://cdn.adskull.io/uploads/motion-source.mp4"
  }'

Accepted Response

{
  "id": "job_01HXVIDEO...",
  "object": "video_generation_job",
  "status": "queued",
  "progress_percent": 0,
  "credits_reserved": 60,
  "credits_used": null,
  "credits_refunded": 0,
  "created_at": "2026-05-17T12:00:00Z",
  "assets": []
}

Completed Response

{
  "id": "job_01HXVIDEO...",
  "object": "video_generation_job",
  "status": "completed",
  "progress_percent": 100,
  "credits_reserved": 60,
  "credits_used": 60,
  "credits_refunded": 0,
  "completed_at": "2026-05-17T12:03:20Z",
  "assets": [
    {
      "id": "asset_01HX...",
      "object": "asset",
      "type": "video",
      "url": "https://cdn.adskull.io/generated/video.mp4",
      "mime_type": "video/mp4",
      "duration_seconds": 8,
      "width": 1080,
      "height": 1920,
      "expires_at": "2026-05-18T12:03:20Z"
    }
  ]
}

Extend a Veo job

veo-3.1 is the only model that supports extension. Each extension call adds 60 credits and a new 8-second segment.

curl https://api.adskull.io/v1/video-generations/job_01HXVEO.../extend \
  -X POST \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Idempotency-Key: extend-001" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Continue: pan up to reveal city skyline" }'

The body is optional. If you omit it, the extension reuses the source job’s original prompt. veo-3.1 with tier=lite is not extendable.

Extend body

Field	Type	Required	Notes
`prompt`	string	No	New instruction for the appended segment (≤ 4096 chars). Falls back to the source job’s prompt.

Possible Errors

HTTP	Code	When it happens
400	`invalid_request`	Model, duration, ratio, source media, or mode combination is invalid.
401	`unauthorized`	API key is missing or invalid.
403	`forbidden`	Key lacks `videos:write` or account is not Creator or higher.
402	`insufficient_credits`	Available credits are below the selected video cost.
422	`content_policy_violation`	Prompt or media is not allowed.
429	`active_job_limit_reached`	Too many active video jobs are already running.
429	`rate_limited`	Key, account, or IP exceeded rate limits.
503	`temporarily_unavailable`	Generation capacity is temporarily unavailable.

Start Here

Features

Core Concepts

Endpoints

Orientation cheatsheet

Create Parameters

Per-model valid combos

Example: vertical Veo 3.1 ad (TikTok-style)

Example: horizontal Kling 3.0 with audio toggle

Example: 30-second single-pass Seedance 2.5

Example: image-to-video with Wan 2.6 (ratio inherits)

Example: edit an existing video (Wan 2.6 V2V)

Example: motion control (Kling 3.0 MC)

Accepted Response

Completed Response

Extend a Veo job

Extend body

Possible Errors

​Endpoints

​Orientation cheatsheet

​Create Parameters

​Per-model valid combos

​Example: vertical Veo 3.1 ad (TikTok-style)

​Example: horizontal Kling 3.0 with audio toggle

​Example: 30-second single-pass Seedance 2.5

​Example: image-to-video with Wan 2.6 (ratio inherits)

​Example: edit an existing video (Wan 2.6 V2V)

​Example: motion control (Kling 3.0 MC)

​Accepted Response

​Completed Response

​Extend a Veo job

​Extend body

​Possible Errors

Endpoints

Orientation cheatsheet

Create Parameters

Per-model valid combos

Example: vertical Veo 3.1 ad (TikTok-style)

Example: horizontal Kling 3.0 with audio toggle

Example: 30-second single-pass Seedance 2.5

Example: image-to-video with Wan 2.6 (ratio inherits)

Example: edit an existing video (Wan 2.6 V2V)

Example: motion control (Kling 3.0 MC)

Accepted Response

Completed Response

Extend a Veo job

Extend body

Possible Errors