预览文档

把 Veo 4 模型 API 接入你的产品工作流

这份开发者指南展示 Veo 4 API 的计划请求流程：创建视频任务、轮询任务状态、接收 Webhook，并在正式上线前预估积分消耗。

打开 API Keys 查看价格

接入流程

四步接好 API

准备后端接入时可按这个流程设计。API Key 保存在服务端，任务异步提交，完成后再保存结果 URL。

创建 API Key

进入 Dashboard > API Keys，准备服务端使用的 Key。浏览器客户端应调用你的后端，不要直接暴露 Key。

提交视频任务

用 prompt、可选 image_urls、画幅、seed、水印和公开可见性设置提交文生视频或图生视频请求。

跟踪进度

使用 task_id 轮询任务端点，直到状态变为 succeeded 或 failed。生产系统可用 Webhook 减少轮询。

保存素材

任务成功后，把 video_url 和 thumbnail_url 写入 CMS、编辑器、自动化流程或用户项目记录。

预览契约

计划中的 REST 接口

下面示例刻意写得具体，方便团队提前设计客户端。正式上线公告前，请把它视为草案契约。

Base URL

请从服务端通过 HTTPS 调用。正式上线时可能提供版本化域名或额外区域端点。

https://veo4api.net/api/video/veo4

鉴权

所有请求使用 Bearer token。API Key 必须放在服务端密钥中，不要进入公开前端包。

Authorization: Bearer YOUR_API_KEY

POSThttps://veo4api.net/api/video/veo4/generate可能调整

创建一个新的异步 Veo 4 视频任务。响应会立即返回 task_id，渲染在后台继续执行。

字段	类型	必填	说明
`prompt`	string	是	视频生成的自然语言指令，建议包含主体、镜头运动、风格和限制条件。
`image_urls`	string[]	否	图生视频任务使用的可公开访问源图片。当前代理接受 image_urls 以及兼容的图片 URL 别名。
`aspect_ratio`	string	否	计划值包含 16:9、9:16 和 1:1。
`extend_task_id`	string	否	请求视频续写工作流时，可传入已完成视频的 task_id。
`seeds`	number	否	可选数字 seed，用于提升输出可复现性。当前接受范围是 10000 到 99999。
`watermark`	string	否	可选水印标签，会透传到视频生成后端。
`enableTranslation`	boolean	否	可选布尔值，用于控制生成前是否翻译 prompt，默认 true。
`public`	boolean	否	可选布尔值，用于标记结果是否可出现在公开展示区域。

cURL

curl -X POST "https://veo4api.net/api/video/veo4/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic dolly shot of a glass greenhouse during sunrise",
    "aspect_ratio": "16:9",
    "watermark": "veo4api",
    "enableTranslation": true
  }'

JavaScript

const response = await fetch("https://veo4api.net/api/video/veo4/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Animate this product photo into a smooth studio orbit shot",
    image_urls: ["https://cdn.example.com/input/product.png"],
    aspect_ratio: "1:1",
    seeds: 12345,
    public: false
  })
});

const data = await response.json();
console.log(data.task_id);

排队响应

{
  "task_id": "veo4_task_01j9example",
  "status": "queued",
  "model": "veo-4",
  "credits_estimated": 180,
  "created_at": "2026-05-17T08:00:00Z"
}

完成任务响应

{
  "task_id": "veo4_task_01j9example",
  "status": "succeeded",
  "progress": 100,
  "video_url": "https://cdn.veo4api.net/results/veo4_task_01j9example.mp4",
  "thumbnail_url": "https://cdn.veo4api.net/results/veo4_task_01j9example.jpg",
  "completed_at": "2026-05-17T08:03:42Z"
}

// Poll the task with:
// GET https://veo4api.net/api/video/veo4/status?task_id={task_id}

异步交付

用 Webhook 接收完成事件

Webhook 交付属于公开 API 契约中的计划能力。在启用前，请先轮询 status 端点，并为未来 webhook_url 字段预留后端处理逻辑。

签名策略

Webhook 签名细节尚未最终确定。建议预留未来签名 Header 校验，保存 task_id，并安全忽略重复事件。

Webhook Payload 示例

{
  "event": "video.succeeded",
  "task_id": "veo4_task_01j9example",
  "status": "succeeded",
  "model": "veo-4",
  "video_url": "https://cdn.veo4api.net/results/veo4_task_01j9example.mp4",
  "credits_charged": 180,
  "created_at": "2026-05-17T08:00:00Z",
  "completed_at": "2026-05-17T08:03:42Z"
}

可靠性

任务状态与错误处理

客户端应围绕明确的任务状态和可重试失败来设计。生成是异步的，所以 200 响应只表示任务已被接受。

状态	含义
`queued`	请求已接受，正在等待可用容量。
`processing`	模型正在渲染或进行后处理。
`succeeded`	视频已就绪，并返回结果 URL。
`failed`	生成失败。展示错误信息，并允许用户修改 prompt 或重试。
`canceled`	任务在完成前被取消。

状态码	建议处理方式
`400`	重试前校验 prompt 长度、image_urls、aspect_ratio、seeds 和公开可见性。
`401`	API Key 缺失、过期或无效。提示用户创建新 Key。
`402`	积分不足。引导用户前往账单页，或降低质量后重试。
`409`	任务请求冲突。当平台返回冲突时，应读取已有任务，不要再创建一个。
`429`	触发限流。使用指数退避，避免高频轮询。
`500`	临时平台或模型错误。稍后重试，并保留原任务记录。

积分规划

计划积分成本

当前价格页使用这些规划数字展示 Veo 4 容量。正式上线前，它们不是最终计费承诺。

标准视频任务

180

每次标准 Veo 4 视频生成的预估积分。

HD 视频任务

240

每次 HD Veo 4 视频生成的预估积分。

这些数字仅用于容量规划。公开 API 的实际限额、质量档位和计费行为仍可能调整。