---
title: "Submit a video generation job"
method: POST
path: "/v1/video/generate"
tags: ["generation"]
---

# Submit a video generation job

`POST /v1/video/generate`

## Request

- Base URL: `https://varosity.ai/api`
- URL: `https://varosity.ai/api/v1/video/generate`
- Auth: HTTP bearer

Developer-facing endpoint. Takes a prompt and model, submits the job immediately, and returns a jobId. Poll GET /v1/jobs/{jobId} every 2–5 seconds until status is 'succeeded' or 'failed'. Requires generate:video scope.

## Request body

- object
  - `prompt` string, required
  - `modelId` string, required: Model ID from GET /v1/models
  - `aspectRatio` '16:9' | '9:16' | '1:1' | '4:5' | '21:9': Each model renders a subset (aspectRatios in GET /v1/models; every video model supports 16:9). An unsupported value is refused with 400 unsupported_aspect_ratio and the supported list.
  - `durationSec` integer: Seconds. The upper limit is the chosen model's maxDurationSec (see GET /v1/models). Many models render fixed lengths (for example 4/6/8 or 5/10 seconds): the request is fitted to the nearest length the model makes, and you are charged for the seconds produced, not the seconds requested.
  - `referenceImageUrl` string, uri
  - `referenceVideoUrl` string, uri: Source or driving video, for models that take one.
  - `audioUrl` string, uri: External audio track for avatar / lip-sync models (omnihuman, heygen-photo-avatar, muapi-latentsync). The provider lip-syncs to THIS track instead of synthesizing its own TTS. For muapi-latentsync, referenceImageUrl carries the source VIDEO url.
  - `authPreference` 'byok' | 'platform'
  - `providerOptions` object: Advanced per-model knobs (e.g. fal veo/kling/seedance resolution/cfgScale/generateAudio, WaveSpeed seed/loop, muapi resolution/effect). Full field list per model: /docs/provider-options.

## Response `200`

Job submitted

- object
  - `ok` boolean
  - `jobId` string, uuid
  - `projectId` string, uuid
  - `status` 'queued' | 'rendering' | 'succeeded'
  - `outputUrl` string, uri, nullable
  - `billingMode` 'byok' | 'platform'

## Other responses

- `400`: Invalid request body, unknown model (unknown_model), a non-video model (not_a_video_model), a duration above the model maximum (duration_exceeds_model_max), or an aspect ratio the model does not render (unsupported_aspect_ratio, with supportedAspectRatios)
- `401`: Unauthorized
- `403`: Insufficient scope (insufficient_scope; needs generate:video)
- `409`: Model unavailable, provider not configured, or no way to pay for it (auth_not_configured: no provider key and not enough credits for the estimate)
- `429`: rate_limited (too many requests; honour Retry-After) or daily_cap_exceeded (this key's daily spend cap is used up; the body has spent_today_cents and daily_cap_cents, there is no Retry-After, and it is not retryable until the 00:00 UTC reset or a higher cap)
- `503`: spend_guard_error: the daily spend cap could not be checked; nothing was submitted

## Changes

- **2026-10-20** `81d0169a4897`: 3 info
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - removed the non-success response with the status `402`

[Operation history](https://skmtc.dev/varosity/apis/varosity-ai-api/changes/v1/video/generate/post.md)

---

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