queue_id,然后轮询 /video/retrieve 直到响应是 video/mp4。
端点
步骤 1:排队生成
请求:download_url 字段:
download_url 是一个预签名的 URL,用于下载完成的视频,而非从 retrieve 响应中读取它。它仅在队列响应中返回一次,因此请将其与 queue_id 一起持久化。这适用于所有四个 Grok Imagine Private 变体:
grok-imagine-text-to-video-privategrok-imagine-image-to-video-privategrok-imagine-reference-to-video-privategrok-imagine-video-to-video-private
grok-imagine-*-video 变体不同,Grok Imagine Private 模型不会因内容审核拒绝而被计费,因此您只为成功生成付费。
为所有后续调用保存 model、queue_id 和 download_url(如有)。
私有下载链接
对于 private 模型,download_url 是您在作业完成后获取已完成文件的方式。该链接是短暂的且单用途的:它的作用是向您交付 MP4,而不是作为长期或广泛共享的 URL。
如果下载中断,您可以从同一环境重试相同的 GET 几次,直到文件完成。这些重试用于从网络抖动中恢复——而非用于无限期地轮询同一链接、跨多个客户端共享它,或像永久媒体 URL 那样嵌入它。这些模式通常会显示为 429 或 410,如果您期望链接像常规文件托管一样运行,这可能会令人惊讶。
为了可靠性,GET 请求应来自一个客户端网络。如果您的 IP 变化一次(例如断开 VPN 后重试),有一些灵活性,但源 IP 的广泛变化通常不会工作。
URL 最多保持有效 24 小时,或直到对象被移除。
如果您需要稳定的 URL、公共播放或随时间反复访问,请先将文件保存到您自己的存储中并从那里提供。
DELETE 撤销链接
当您完成获取文件后——或如果您决定不保留它——可以对同一个 download_url 调用 DELETE。该请求不需要 Venice API 密钥。这是可选的,但在隐私重要时建议,因为 Venice 之外的某些代理和中间件会保留完整 URL 的日志,删除链接是缩短预签名 URL 存在窗口的最简单方法。
/video/retrieve 直到 COMPLETED → GET 该 download_url(如果传输中断,轻度重试) → 将文件保存到您需要的位置 → 如果您希望使链接失效,对 download_url 调用 DELETE → 如果您仍使用基于队列的清理,可选调用 /video/complete。
步骤 2:轮询完成
请求:
处理中响应(200, application/json):
average_execution_time 估算剩余等待时间。
完成响应(200, video/mp4):
响应体是原始二进制视频数据。保存到文件。
完成响应(200, 带 "COMPLETED" 的 application/json):
对于在排队时返回 download_url 的模型,retrieve 始终返回 JSON。使用 GET download_url(无 auth 头)获取视频。请参阅私有下载链接了解这些 URL 的工作方式、重试和可选的 DELETE。
步骤 3:清理(可选)
可以在 retrieve 时自动删除:/video/complete:
完整示例
请求参数
Queue 请求
队列验证是模型特定的。在调用
/video/queue 之前查看 /models?type=video 以了解每个模型支持的请求字段。
Quote 请求
Retrieve 请求
Complete 请求
图像到视频
对于 image-to-video 模型,通过image_url 传递源图像。prompt 描述所需的运动,而非图像内容。
价格报价
在生成之前获取精确成本。仅发送定价输入(model、duration 以及可选的 resolution、aspect_ratio、audio):
请求:
错误
轮询策略
- 以一定间隔(例如每 5 秒)轮询
/video/retrieve - 如果
Content-Type为application/json且status为"PROCESSING",等待并再次轮询。使用average_execution_time和execution_duration(毫秒)估算剩余时间 - 如果
Content-Type为video/mp4,将响应体保存为输出文件 - 如果
Content-Type为application/json且status为"COMPLETED",从队列响应中GETdownload_url以获取视频(请参阅私有下载链接) - 如果使用了
download_url,请在完成后考虑对该 URL 调用DELETE以缩短预签名 URL 的存在时间;然后可选地在 retrieve 上设置delete_media_on_completion: true或调用/video/complete进行基于队列的清理 - 将
404视为无效、过期或已删除的媒体;用重试/退避处理500/503