Veo 3.1 视频生成使用指南

Veo 3.1 当前在平台内走统一 /v1/videos 视频任务端点。本文只写用户可直接调用的模型 ID、请求字段、轮询流程和当前公开售价。

接口地址 & 模型

• 创建任务：POST https://www.yuzhixiaolongxia.com/v1/videos
• 查询任务：GET https://www.yuzhixiaolongxia.com/v1/videos/{task_id}
• 下载视频：GET https://www.yuzhixiaolongxia.com/v1/videos/{task_id}/content
• API 模型 ID：veo3.1-fast / veo3.1-pro
• 令牌分组：sora-veo-grok-video

模型 ID 不要写错

当前真实可用 ID 只有 veo3.1-fast 和 veo3.1-pro。调用前直接从模型广场复制，避免手打出错。

模型选择

模型 ID	适合场景	推荐用法	当前售价
veo3.1-fast	快速试稿、批量出片、社媒素材	先试提示词和镜头，再决定是否上 Pro	0.308 元/秒
veo3.1-pro	质量优先、广告短片、终稿交付	少量终稿任务，轮询等待时间要放宽	1.538 元/秒

当前公开文档不按旧的 720p / 1080p / 4K 分档价对账。需要高分辨率时可以在 prompt 和 size 中明确目标，但最终以任务结果和控制台调用日志为准。

参数表

参数	类型	必填	说明
model	string	是	veo3.1-fast 或 veo3.1-pro
prompt	string	是	视频描述，建议写清镜头、动作、画面比例
seconds	string/int	否	建议显式传，例如 8
duration	int	否	兼容字段；新接入优先用 seconds
size	string	否	目标尺寸/规格，是否生效以实际返回为准
image	string	否	单张参考图 URL/base64
images	string[]	否	多张参考图 URL/base64
input_reference	file/string	否	multipart 参考图文件，或兼容参考图字段

图生视频字段

图生视频必须传 image、images 或 input_reference，不要只在 prompt 写“这张图片”。

文生视频示例

curl -X POST "https://www.yuzhixiaolongxia.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast",
    "prompt": "A cinematic shot of a chef placing crawfish on a black slate plate, steam rising, slow camera push in, soft top light, realistic restaurant commercial",
    "seconds": "8",
    "size": "1280x720"
  }'

查询：

curl "https://www.yuzhixiaolongxia.com/v1/videos/task_xxx" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

下载：

curl -L "https://www.yuzhixiaolongxia.com/v1/videos/task_xxx/content" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  --output veo-result.mp4

图生视频示例

curl -X POST "https://www.yuzhixiaolongxia.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-pro",
    "prompt": "Use image 1 as the first frame. The camera stays fixed, the person smiles and waves, then shows the product to the audience, realistic indoor background",
    "seconds": "8",
    "images": [
      "https://example.com/reference.jpg"
    ]
  }'

multipart 本地文件：

curl -X POST "https://www.yuzhixiaolongxia.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -F "model=veo3.1-pro" \
  -F "prompt=Use the uploaded image as the first frame. Fixed camera, natural product demonstration, realistic motion" \
  -F "seconds=8" \
  -F "input_reference=@reference.jpg"

计费与对账

Veo 3.1 按秒估算，任务提交时预扣，任务失败后会回退预扣。

模型	当前售价	8 秒示例预扣
veo3.1-fast	0.308 元/秒	0.308 × 8 = 2.464 元
veo3.1-pro	1.538 元/秒	1.538 × 8 = 12.304 元

预扣金额 = 当前售价（元/秒） × seconds × 尺寸系数

最终金额以控制台「调用日志」为准。不要用旧的分辨率分档价做客户对账。

生产接入建议

• 默认先用 veo3.1-fast 试提示词和镜头语言，确认方向后再切 veo3.1-pro。
• Pro 任务质量更高，但排队和生成时间也更长；客户端不要把 HTTP 请求当同步生成来等结果。
• POST /v1/videos 返回 200 和任务 ID 只代表提交成功，最终必须轮询到 completed。
• 出现 task timeout 时按失败处理，等待预扣回退后降低规格或切回 veo3.1-fast 重试。

常见错误

错误/现象	原因	处理
model not found	模型 ID 不是当前可用值	改为 veo3.1-fast 或 veo3.1-pro
prompt is required	没传 prompt	补 prompt
图生视频没吃到图	没传图片字段	传 image、images 或 input_reference
结果不是预期 4K	生成结果和播放器展示可能不同	下载原视频查看真实分辨率，按调用日志对账
任务 failed / task timeout	队列繁忙、高规格任务等待过久或内容不适合生成	保存错误响应，等退款后降低规格或换 veo3.1-fast

提示词建议

Veo 3.1 类模型对镜头语言比较敏感，建议写清：

要素	示例
镜头	fixed camera / slow push in / close-up
动作	smiles and waves / shows the product to the camera
场景	bedroom background remains unchanged
风格	realistic motion, natural lighting, no scene change

上一步：Sora-2 视频生成使用指南　|　下一步：Grok-Video 视频生成使用指南