venice-video

Files (1)

• SKILL.md

SKILL.md (first lines)

# Venice Video

Video is **asynchronous** — like audio music. Four live endpoints plus one retired one:

| Endpoint | Purpose |
|---|---|
| `POST /video/quote` | Price in USD (no charge, no job). No API key needed, except for upscale models. |
| `POST /video/queue` | Validate, charge, and enqueue. Returns `queue_id` immediately. |
| `POST /video/retrieve` | Poll status, download `video/mp4`, or receive the job's failure. |
| `POST /video/complete` | Cleanup of the finished media. Currently rejects `queue_id`s from `/video/queue`, so use `delete_media_on_completion` on retrieve instead (see [step 4](#4-clean-up-with-videocomplete)). |
| `POST /video/transcriptions` | **Retired — always returns `410`.** See [below](#videotranscriptions-retired). |

`/video/queue`, `/video/retrieve`, and `/video/complete` accept a Bearer API key or an x402 `SIGN-IN-WITH-X` wallet header (see [`venice-x402`](../venice-x402/SKILL.md)).

## Use when

- You need text-to-video, image-to-video, first/last-frame transitions, reference-to-video (R2V), video-to-video, video upscale, or video-with-audio.
- You can tolerate async execution (seconds to several minutes depending on model, duration, and queue depth — `/video/retrieve` returns `average_execution_time` and `execution_duration` for a live estimate).
- You want to price a job precisely before committing (`/video/quote`).

Not for: understanding or summarizing an existing video — use [`venice-chat`](../venice-chat/SKILL.md) with a `video_url` content part.

## Pick a model first

Every field below is model-specific. Read the model's constraints from `GET /models?type=video` (see [`venice-models`](../venice-models/SKILL.md)) before building a request:

- `constraints.model_type` — `text-to-video`, `image-to-video` (includes R2V and transition models), or `video` (video-to-video, motion control, upscale).
- `constraints.durations`, `aspect_ratios`, `resolutions` — the exact accepted strings (case-sensitive: MiniMax H3 Max uses `480P` / `768P` / `1080P`, MiniMax H3 uses `768P` / `2K`).
- `constraints.audio_configurable` — only then may you send `audio`.
- `constraints.audio_input` — only then may you send `audio_url`.
- `constraints.prompt_character_limit` — present when the model sets its own limit; otherwise the limit is 2500 characters.

The request schema is **strict per model**: a field the model does not support is a `400` (e.g. `"This model does not support aspect_ratio"`), not silently ignored.

## Lifecycle — generation

### 1. Price with `/video/quote`

```bash
curl https://api.venice.ai/api/v1/video/quote \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-2.6-text-to-video",
    "duration": "5s",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": true
  }'
```

Response: `{"quote": 0.55}` (USD).

- Required: `model`, and `duration` for models with fixed durations.
- `resolution` and `aspect_ratio` fall back to the model default when omitted.
- The quote endpoint **discards** fields a model doesn't use (e.g. `audio` on a model with `audio_configurable: false`, `aspect_ratio` on a model with no `aspect_ratios`, unknown keys) — `/video/queue` rejects them. A successful quote does not prove the queue body is valid.
- **Upscale models** (`topaz-video-upscale`): quote requires a Bearer API key (`403` without one, so x402 wallets can't quote them — queue directly and rely on the `402` balance check) and `video_url` — Venice fetches the file to detect duration, FPS, and height (`400` if it can't read it). `duration` is ignored. Pass `upscale_factor` (`1` / `2` / `4`) to price the factor you will queue; `resolution: "1x"` / `"2x"` / `"4x"` is a deprecated alias.
- **Video-to-video models** (e.g. `wan-2-7-video-to-video`): `video_url` is required; duration is detected from the file.
- **R2V models with reference-video support** (Seedance 2.x, MiniMax H3 / H3 Max, Wan 3.0 R2V, …): pass `reference_video_total_duration` (aggregate seconds of all reference videos, capped at the model's aggregate limit — e.g. 15 for Seedance 2.0 / H3 / Wan 3.0, 30 for Seedance 2.5; over the cap is `400`). Reference video is billed, so omitting it returns the no-reference price, which under-quotes. `reference_image_count` (≤ the model's reference-image cap, else `400`) prices models billed per input image; omitted, one image is billed.

### 2. Submit with `/video/queue`

```bash
curl https://api.venice.ai/api/v1/video/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-2.6-text-to-video",
    "prompt": "Commerce being conducted in the city of Venice, Italy.",
    "negative_prompt": "low resolution, worst quality, defects",
    "duration": "5s",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": true
  }'
```

Response: `{ "model": "...", "queue_id": "uuid" }`, plus `download_url` for VPS-backed models.

- Validation and the balance check happen before the `200`; API-key callers are also charged then (x402 wallet callers are charged once the job is accepted). Content screening and the provider submit run **after** the response, so those failures are reported on `/video/retrieve`, not here. Failures are normally refunded (`credits_refunded` in the error body reports the outcome where present), with one exception: the Runway models (`runway-gen4-5`, `runway-gen4-5-text`, `runway-gen4-turbo`) keep the charge when the provider rejects the request on content policy (`credits_refunded: false`).
- `download_url` is returned for **VPS-backed** models — currently every Grok Imagine video model, including the `*-private` ids and `grok-imagine-1-5-lite-text-to-video` / `grok-imagine-1-5-lite-image-to-video`. Decide by whether the queue response contains `download_url`, not by the model id. When it does, `/video/retrieve` returns JSON status only; `GET` the `download_url` (no auth header) once status is `COMPLETED`. Valid up to 24 h.

### 3. Poll with `/video/retrieve`

```bash
curl https://api.venice.ai/api/v1/video/retrieve \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan-2.6-text-to-video","queue_id":"...","delete_media_on_completion":false}' \
  --output out.mp4
```

Body: `model` + `queue_id` (both required), optional `delete_media_on_completion` (default `false`). No other keys are accepted.

- Processing: `200` JSON `{"status":"PROCESSING","average_execution_time":145000,"execution_duration":53200}` (ms; `average_execution_time` is a P80 estimate).
- Completed (most models): `200` binary `video/mp4` body.
- Completed (VPS-backed): `200` JSON `{"status":"COMPLETED", ...}` — fetch the `download_url` from the queue response.
- Failed: a non-`200` JSON error (see [Errors](#errors)). Terminal failures (submit failures, content-policy rejections, provider-side failures, expired media) are recorded on the job, so re-polling the same `queue_id` returns the same error. A `429` is transient — back off and poll again.
- `delete_media_on_completion: true` requests deletion of the stored output once it has been returned, replacing the separate `/video/complete` call.
- `queue_id`s are scoped to the key's user and expire after 24 h; unknown or expired ids return `400` `"Request ID is invalid."`.

### 4. Clean up with `/video/complete`

```bash
curl https://api.venice.ai/api/v1/video/complete \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"...","queue_id":"..."}'
```

Body: `model` + `queue_id` only. Response: `200` `{"success": true}`, or `{"success": false}` if the delete did not go through. Currently it returns `400` `"Request ID is invalid."` for `queue_id`s issued by `/video/queue`, so don't rely on it: clean up by polling with `delete_media_on_completion: true`.

## `/video/queue` request fields

| Field | Type | Notes |
|---|---|---|
| `model` | string | Required. |
| `prompt` | string | Required (≥ 1 non-whitespace char) except for upscale models and `minimax-h3-max-multi-angle`. Max length per model: 2500 default; `constraints.prompt_character_limit` otherwise (from 1000 for Runway up to 20000 for Wan 3.0). |
| `negative_prompt` | string | Same max length as `prompt`. Ignored by models without negative-prompt support. |
| `duration` | string | Required, from `constraints.durations` (values span `1s`–`30s`). Upscale and video-to-video models: omit it (server detects the source length) or send seconds as a string such as `"12.5"` (≤ 300) — the literal `"Auto"` is rejected. `seedance-2-5-reference-to-video-basic` also accepts `"-1"` / `"auto"` (match the source clip). |

From veniceai/skills, MIT.

More from veniceai/skills