Venice视频

视频生成本质上是异步的：从提交请求到拿到成片，中间可能等待数秒到几分钟，还涉及排队、轮询、下载和清理。直接把同步 API 套在视频上，要么超时，要么无法精确控制成本。Venice Video 通过五个端点把这条链路拆成可观察、可中断、可审计的步骤，让你在编码时就能预测费用、处理失败和回收资源。

核心能力

支持五类任务：

• 文生视频（text-to-video）：仅用 prompt 生成动态画面。
• 图生视频（image-to-video）：用 image_url 作为首帧，end_image_url 作为尾帧或过渡参考。
• 视频超分辨率（video upscale）：对已有视频做 1×/2×/4× 画质增强，需使用 upscale_factor 而不是 resolution。
• 带音频视频（video-with-audio）：通过 audio_url 添加背景音乐（WAV/MP3，≤30 秒、≤15 MB），或直接让模型生成音频。
• YouTube 转写（/video/transcriptions）：同步返回 YouTube URL 的音频转录文本，不走队列。

所有任务都遵循同一套生命周期：报价 → 提交 → 轮询 → 完成。你先用 /video/quote 获取精确的 USD 报价（不扣费、不生成任务），再决定是否提交 /video/queue。提交时会预留资金，返回 queue_id；随后用 /video/retrieve 轮询状态，完成后根据模型类型获取二进制 video/mp4 或 download_url；最后调用 /video/complete 显式删除 Venice 存储中的媒体。

关键步骤与参数

提交队列时，QueueVideoRequest 的字段决定了生成行为。model 必填，需通过 GET /models?type=video 确认可用性。prompt 必填，长度因模型而异（2500–3500 字符）。duration 是必填的，即使设置为 Auto 也必须显式传入，否则会返回 400。aspect_ratio 支持 1:1、9:16、16:9 等常见比例，但部分模型会忽略此字段。resolution 和 upscale_factor 不能混用：超分模型只认 upscale_factor，普通生成模型用 resolution 指定 256p 到 4k。

对于需要角色或风格一致性的任务，reference_image_urls 最多 9 张参考图，elements 最多 4 个元素（每个元素可包含正面图、最多 3 张参考图和视频 URL），scene_image_urls 最多 4 张场景图。在 prompt 中用 @Element1、@Image2 引用这些资源。image_url、end_image_url、audio_url、video_url 均支持 URL 或 data: URL，但后者会计入 payload 体积，过大的 base64 视频可能触发 413。

适用边界与注意点

异步意味着你必须处理轮询和超时。/video/retrieve 返回的 average_execution_time 和 execution_duration 是毫秒级估算，实际耗时取决于模型、时长和队列深度。下载策略需要兼容两条路径：非 VPS 模型完成后直接返回二进制 video/mp4，VPS 模型则返回 download_url（仅在队列响应中出现，24 小时后过期，需尽快下载）。delete_media_on_completion: true 可在成功获取后自动删除媒体，减少手动清理。

错误处理要覆盖常见状态码：400 参数错误，401 权限不足，402 余额不足，403 地区不可用，413 请求体过大，422 内容策略违规，500 推理失败，503 模型满载（尤其在 /video/retrieve 上）。注意 /video/queue 的文档未列出 503，上游容量问题可能以 500 形式出现，而轮询时 503 才表示队列积压。

YouTube 转写是同步的，只接受 YouTube URL，不处理本地上传。对于任意音频文件，应改用 venice-audio-transcription。如果你需要从本地视频中提取音频再转写，可以先用 ffmpeg 剥离音轨，再调用音频转写接口。

最后，提交前务必用 /video/quote 估算成本，避免意外扣费。这个技能适合需要精细控制视频生成流程、且能接受异步轮询的工程师，而不是追求一键出片的端到端产品。