venice-video（威尼斯视频）

Venice Video

Video is asynchronous — like audio music. Five endpoints:

Use when

• You need text-to-video, image-to-video, video upscale, video-with-audio, or video transcription.
• You can tolerate async execution (single-digit seconds to several minutes depending on model, duration, and queue depth — inspect average_execution_time and execution_duration on /video/retrieve for your job's live estimate).
• You want to price a job precisely before committing (/video/quote).

Lifecycle — generation

1. Price with /video/quote

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

Response: {"quote": 0.35} USD.

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-7-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", "download_url": "https://..."}.

• download_url only appears for VPS-backed models. When present, the retrieve endpoint returns JSON status only — fetch this URL to download. Valid 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":"...","queue_id":"..."}' \
  --output out.mp4

• Processing: JSON {"status":"PROCESSING","average_execution_time":145000,"execution_duration":53200} (ms).
• Completed (non-VPS): binary video/mp4 body.
• Completed (VPS-backed): {"status":"COMPLETED",...} — fetch the download_url from the queue response.
• delete_media_on_completion: true auto-deletes after successful retrieve.

4. Finalize 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":"..."}'

QueueVideoRequest fields

Availability depends on the model — check GET /models?type=video.

Common recipes

Text → video with audio

{
  "model": "wan-2-7-text-to-video",
  "prompt": "A golden retriever chasing a frisbee in slow motion at sunset.",
  "duration": "6s",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "audio": true
}

Image → video

{
  "model": "<image-to-video model>",
  "prompt": "Camera slowly zooms out, revealing the cityscape.",
  "image_url": "https://example.com/cityscape.jpg",
  "duration": "5s",
  "aspect_ratio": "16:9"
}

Video upscale

{
  "model": "<upscale model>",
  "video_url": "data:video/mp4;base64,...",
  "upscale_factor": 2,
  "duration": "Auto"
}

Multi-element consistency (Kling O3 R2V-style)

{
  "model": "<advanced-model>",
  "prompt": "@Element1 walks toward @Element2 against @Image1.",
  "elements": [
    { "frontal_image_url": "<char1.png>", "reference_image_urls": ["<alt1.png>"] },
    { "frontal_image_url": "<char2.png>" }
  ],
  "scene_image_urls": ["<street-scene.jpg>"]
}

/video/transcriptions (sync)

Transcribe a YouTube video URL directly — no queue.

curl https://api.venice.ai/api/v1/video/transcriptions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=...","response_format":"json"}'

Response: {"transcript":"...","lang":"en"} (JSON) or plain text/plain body when response_format: text.

For arbitrary audio files, use venice-audio-transcription instead.

Full polling loop

async function waitForVideo(model: string, queueId: string, downloadUrl?: string) {
  while (true) {
    const res = await fetch(`${base}/video/retrieve`, {
      method: 'POST', headers,
      body: JSON.stringify({ model, queue_id: queueId }),
    })
    const ct = res.headers.get('content-type') ?? ''
    if (ct.startsWith('video/')) {
      return Buffer.from(await res.arrayBuffer())
    }
    const body = await res.json()
    if (body.status === 'COMPLETED' && downloadUrl) {
      const v = await fetch(downloadUrl)
      return Buffer.from(await v.arrayBuffer())
    }
    if (body.status !== 'PROCESSING') throw new Error(`unexpected ${body.status}`)
    await new Promise(r => setTimeout(r, 5000))
  }
}

Errors

/video/queue does not document 503 in the spec — upstream capacity issues surface there as 500. Watch for 503 specifically on /video/retrieve.

Gotchas

• duration is required on /video/queue. Even Auto is a valid explicit value.
• download_url is only sometimes returned at queue time. Always handle both paths: binary from /retrieve OR fetching download_url after status COMPLETED.
• download_url expires in 24 h — download promptly.
• Upscale models use upscale_factor *instead of* resolution.
• reference_image_urls[] is capped at 9 entries, elements[] at 4, scene_image_urls[] at 4. Over-limit is 400.
• data: URLs count toward payload size; large base64 videos may trip 413 — prefer hosted URLs.
• /video/transcriptions is YouTube-URL-only; it does not accept arbitrary video uploads (use ffmpeg to strip audio, then /audio/transcriptions).