---
title: "Create a video job (Idempotency-Key required): holds its estimate from the balance and queues it; 202 with the video"
method: POST
path: "/v1/videos"
tags: ["platform-api"]
---

# Create a video job (Idempotency-Key required): holds its estimate from the balance and queues it; 202 with the video

`POST /v1/videos`

## Request

- Base URL: `https://api.cuddler.ai`
- URL: `https://api.cuddler.ai/v1/videos`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, required: Required. One key per logical request (e.g. `ep03-shot042-take1`), never reusable: the same key and body answer with the original object and `Idempotent-Replayed: true`; the same key with a different body is 409 (and so is any reuse once the job's request trace was removed, 180 days after it finished).

## Request body

- object
  - `model` 'seedance-2.5' | 'seedance-2.0' | 'seedance-2.0-mini' | 'minimax-h3' | 'wan-3.0' | 'wan-3.0-prime' | 'happyhorse-1.0' | 'happyhorse-1.1' | 'wan-2.6' | 'wan-2.7' | 'ltx-2.5' | 'minimax-hailuo-2.3' | 'pixverse-6' | 'grok-video-1.5' | 'kling-3.0' | 'kling-2.6' | 'kling-2.5-turbo' | 'kling-o1' | 'kling-o3' | 'vidu-q4-preview' | 'runway-gen4.5' | 'runway-gen4-turbo' | 'veo-3.1' | 'veo-3.1-fast' | 'veo-3.1-lite' | 'veo-3' | 'veo-3-fast' | 'veo-2' | 'gemini-omni-flash', required
  - `mode` 'text' | 'image' | 'reference' | 'edit' | 'extend' | 'motion-control' | 'image-reference' | 'video-reference' | 'first-last-frame'
  - `variant` 'default' | 'fast' | 'pro' | 'standard' | 'turbo' | '4k' | 'base' | 'utility' | 'utility-pro'
  - `max_usd` string: Maximum USD this job may charge; creation refuses a larger hold and settlement never exceeds this ceiling
  - `prompt` string, required
  - `duration` integer, required
  - `resolution` '360p' | '480p' | '540p' | '720p' | '768p' | '1080p' | '1440p' | '0.5K' | '1K' | '2K' | '4K'
  - `aspect_ratio` '16:9' | '9:16' | '4:3' | '3:4' | '1:1' | '21:9' | 'adaptive' | '9:21' | '4:5' | '5:4' | '2:3' | '3:2' | '5:2'
  - `generate_audio` boolean
  - `seed` integer
  - `camera_fixed` boolean
  - `character_orientation` 'image' | 'video'
  - `fps` integer
  - `return_last_frame` boolean
  - `first_frame` string: An upload id (upl_…), or a public https:// URL the API fetches once when the job is created
  - `last_frame` string: An upload id (upl_…), or a public https:// URL the API fetches once when the job is created
  - `reference_images` string[]
  - `reference_videos` string[]
  - `reference_audios` string[]
  - `task_type` 'auto' | 'edit' | 'extend'
  - `webhook_url` string, uri
  - `metadata` object

## Response `200`

Replay: this Idempotency-Key already created this video

- object
  - `object` 'video', required
  - `id` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
  - `stage` 'preparing_references'
  - `poll_after_seconds` integer
  - `model` 'seedance-2.5' | 'seedance-2.0' | 'seedance-2.0-mini' | 'minimax-h3' | 'wan-3.0' | 'wan-3.0-prime' | 'happyhorse-1.0' | 'happyhorse-1.1' | 'wan-2.6' | 'wan-2.7' | 'ltx-2.5' | 'minimax-hailuo-2.3' | 'pixverse-6' | 'grok-video-1.5' | 'kling-3.0' | 'kling-2.6' | 'kling-2.5-turbo' | 'kling-o1' | 'kling-o3' | 'vidu-q4-preview' | 'runway-gen4.5' | 'runway-gen4-turbo' | 'veo-3.1' | 'veo-3.1-fast' | 'veo-3.1-lite' | 'veo-3' | 'veo-3-fast' | 'veo-2' | 'gemini-omni-flash', required
  - `prompt` string, required
  - `duration` integer, required
  - `resolution` '360p' | '480p' | '540p' | '720p' | '768p' | '1080p' | '1440p' | '0.5K' | '1K' | '2K' | '4K', required
  - `aspect_ratio` '16:9' | '9:16' | '4:3' | '3:4' | '1:1' | '21:9' | 'adaptive' | '9:21' | '4:5' | '5:4' | '2:3' | '3:2' | '5:2', required
  - `generate_audio` boolean, required
  - `created_at` string, required
  - `started_at` string, nullable, required
  - `completed_at` string, nullable, required
  - `queue_position` integer, nullable, required
  - `estimate` object, required
    - `tokens` integer, required
    - `usd` string, required
    - `hold_usd` string, required
  - `usage` object, nullable, required
    - `tokens` integer, required
    - `usd` string, required
    - `usd_micros` integer, required
  - `output` object, nullable, required
    - `url` string, uri, required
    - `url_expires_at` string, required
    - `retained_until` string, required
    - `width` integer, nullable, required
    - `height` integer, nullable, required
    - `duration` number, nullable, required
    - `has_audio` boolean, required
    - `last_frame_url` string, uri, nullable, required
  - `error` object, nullable, required
    - `code` 'content_policy' | 'reference_rejected' | 'invalid_parameters' | 'upstream_error' | 'timeout' | 'internal_error', required
    - `message` string, required
  - `metadata` object, required
  - `price_version` string, required
  - `api_key_id` string, required

## Other responses

- `202`: Created: the video, with its estimate and hold. Usually queued or already running; already failed (nothing charged, see error) when it could not be prepared or submitted
- `400`: invalid_request — validation failed (details.issues): Idempotency-Key, durations, resolutions, aspect ratios, frame and reference rules (task_type only with reference media; seed / camera_fixed only on seedance-2.5; a field the model does not take, see GET /v1/models → request_fields), uploads that are not ready or not this organization's
- `401`: unauthorized — no key, or an unknown or revoked one (WWW-Authenticate: Bearer)
- `402`: insufficient_balance — the available balance does not cover the hold
- `403`: model_not_enabled; organization_suspended; forbidden — a test key
- `404`: not_found — the Platform API is switched off, or the object does not exist
- `409`: idempotency_conflict — the key was already used with a different body
- `422`: content_blocked — the prompt is not allowed under the content policy
- `429`: rate_limited / queue_full / daily_limit_reached (Retry-After)
- `500`: internal_error — quote request_id when contacting support
- `503`: unavailable — moderation or storage could not answer; nothing was held, retry (Retry-After)

---

[API](https://skmtc.dev/cuddler/apis/cuddler-platform-api.md) · [All operations](https://skmtc.dev/cuddler/apis/cuddler-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cuddler/apis/cuddler-platform-api/revisions/f03943ceadff?raw)