> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adskull.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Videos
> Generate, edit, extend, and motion-control AI 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](/public/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)
```bash theme={"theme":"github-dark"}
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
```bash theme={"theme":"github-dark"}
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.
```bash theme={"theme":"github-dark"}
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)
```bash theme={"theme":"github-dark"}
# 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)
```bash theme={"theme":"github-dark"}
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)
```bash theme={"theme":"github-dark"}
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
```json theme={"theme":"github-dark"}
{
"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
```json theme={"theme":"github-dark"}
{
"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.
```bash theme={"theme":"github-dark"}
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. |