Venice Video

Venice Video

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

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

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 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) 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

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

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

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). 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_ids 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

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_ids issued by /video/queue, so don't rely on it: clean up by polling with delete_media_on_completion: true.

/video/queue request fields

Every media URL must be a data: URL or an http(s):// URL on a public host — private, loopback, link-local, and cloud-metadata addresses are rejected with 400. bitrate_mode, image_references, video_references, voice_id, and anon_user_id are accepted but not listed in the published OpenAPI schema.