---
title: "Generate a video (async)"
method: POST
path: "/v1/videos/generate"
tags: ["Videos"]
---

# Generate a video (async)

`POST /v1/videos/generate`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/videos/generate`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

Queue a text-to-video generation job (optionally seeded by a library image as the start frame).
Returns immediately with a `job_id` - poll `GET /v1/jobs/{id}` until `status` is `completed`.
Allowed `duration` and `resolution` values depend on the chosen model.

## Request body

- object
  - `prompt` string, required: Description of the video to generate.
  - `model` 'omni' | 'grok' | 'kling' | 'seedance': Video model to use. omni is Gemini Omni Flash. The retired id veo3 is still accepted and runs on omni.
  - `aspect_ratio` '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '3:2' | '2:3': Aspect ratio of the video. Defaults to the start image's shape when image_file_uuid is given, else 16:9. omni renders 16:9 or 9:16 only: portrait ratios become 9:16, square and landscape ratios 16:9.
  - `duration` integer: Length in seconds. omni: 3 to 10 (values outside are clamped). grok: 5, 8, 10 or 15. kling: 3, 5, 8, 10 or 15. seedance: 4, 6, 8, 10, 15, 20 or 30. For grok, kling and seedance other values snap down to the nearest of these (below the first, the first), so the generated length is the billed length; the 202 response reports the duration used.
  - `resolution` '720p' | '480p' | 'standard' | 'pro': Per model: omni 720p; grok 480p or 720p; kling standard or pro; seedance 480p or 720p. Omit it for the model's default (omni 720p, grok 480p, kling standard, seedance 480p); a value the model does not support also falls back to that default.
  - `negative_prompt` string: What the video should avoid. omni has no negative prompt parameter, so it is appended to the prompt text.
  - `image_file_uuid` string: Optional uuid of an image already in your library to use as the start frame (no upload needed).
  - `start_frame_data` string: The start frame inline, as base64 or a data URL. Use this or `image_file_uuid`.
  - `end_image_file_uuid` string: Optional uuid of a library image to use as the end frame. Needs a start frame; omni, kling and seedance only.
  - `end_frame_data` string: The end frame inline, as base64 or a data URL. Use this or `end_image_file_uuid`.
  - `reference_image_uuids` string[]: omni only: up to 3 images from your library the video should match (look, characters, products).
  - `client_ref` string: Idempotency key (letters, digits, . _ : -). A repeat with the same client_ref within 24 hours returns the first response and is not charged again; while the first is still being queued the repeat gets 409 request_in_progress.
  - `options` object: Model-specific options.

## Response `202`

Job queued. `data` also carries `model`, `duration`, `resolution` and `aspect_ratio`: the values that will be generated and billed, after defaults and snapping. A `client_ref` repeat gets the first response again, with the header `Idempotent-Replayed: true`.

- JobQueued
  - `success` boolean
  - `data` object
    - `job_id` integer
    - `generation_id` integer
    - `generation_uuid` string, uuid
    - `status` string
    - `estimated_credits` number, float
  - `timestamp` string, date-time

## Other responses

- `400`: Missing prompt, both forms of one frame, or a frame that is not a usable image
- `401`: Missing or invalid API key
- `402`: Insufficient credits
- `403`: A frame file belongs to another user
- `404`: image_file_uuid or end_image_file_uuid not found
- `409`: request_in_progress: the first request with this client_ref is still being queued
- `413`: A frame image is larger than 10 MB
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

[API](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api.md) · [All operations](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/revisions/28c74f46051c?raw)