API 参考

Veo 3.1 AI 视频生成完整 API 文档

概述

Veo 3.1 API 允许您通过编程方式从文本描述或图片生成 AI 视频。我们的 RESTful API 设计简洁、功能强大,易于集成到您的应用程序中。

基础 URL

https://veo3o1.com/api

认证

所有 API 请求都需要使用 API 密钥进行认证。在 Authorization 请求头中包含您的 API 密钥:

Authorization: Bearer YOUR_API_KEY

您可以在账户仪表板中生成 API 密钥。


生成视频

从文本或图片创建新的 AI 视频。

端点

POST /generate-video

请求体

{
  "generationType": "text_to_video" | "image_to_video",
  "prompt": "Your video description",
  "aspectRatio": "auto" | "16:9" | "9:16",
  "imageUrl": "https://...", // Required if generationType is "image_to_video"
  "imageKey": "r2-key" // Optional, for uploaded images
}

参数

参数类型必填描述
generationTypestring生成类型:text_to_videoimage_to_video
promptstring您想要生成的视频描述
aspectRatiostring视频宽高比。默认:auto
imageUrlstring条件必填generationTypeimage_to_video 时必填
imageKeystring已上传图片的存储密钥

响应

{
  "code": 0,
  "msg": "Success",
  "data": {
    "uuid": "video-uuid-123",
    "status": "pending",
    "generationType": "text_to_video",
    "prompt": "Your video description",
    "aspectRatio": "16:9",
    "createdAt": "2025-10-16T10:00:00Z"
  }
}

示例

curl -X POST https://veo3o1.com/api/generate-video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generationType": "text_to_video",
    "prompt": "A beautiful sunset over the ocean with waves gently lapping the shore",
    "aspectRatio": "16:9"
  }'

获取视频状态

检查视频生成请求的状态。

端点

GET /video-status/{uuid}

参数

参数类型必填描述
uuidstring生成请求返回的视频 UUID

响应

{
  "code": 0,
  "msg": "Success",
  "data": {
    "uuid": "video-uuid-123",
    "status": "completed" | "pending" | "processing" | "failed",
    "videoUrl": "https://...", // Available when status is "completed"
    "progress": 85, // Processing progress (0-100)
    "estimatedTime": 120 // Estimated seconds remaining
  }
}

状态值

  • pending:视频已排队等待处理
  • processing:视频正在生成中
  • completed:视频已就绪,可供下载
  • failed:生成失败(请查看错误信息)

上传图片

上传图片用于图片转视频生成。

端点

POST /upload-video-image

请求

使用 multipart/form-data 上传图片文件。

curl -X POST https://veo3o1.com/api/upload-video-image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

响应

{
  "code": 0,
  "msg": "Upload successful",
  "data": {
    "imageUrl": "https://...",
    "imageKey": "r2-key-123"
  }
}

支持的格式

  • JPEG/JPG
  • PNG
  • WebP
  • 最大文件大小:50MB

错误代码

代码描述
0成功
1000参数无效
1001积分不足
1002认证失败
1003超出速率限制
5000服务器错误

错误响应示例

{
  "code": 1001,
  "msg": "Insufficient credits",
  "data": {
    "required": 2,
    "current": 0
  }
}

最佳实践

  1. 合理轮询:每 5-10 秒检查一次视频状态,不要持续轮询
  2. 处理错误:实现带指数退避的重试逻辑
  3. 缓存结果:存储已生成的视频以避免重复生成
  4. 使用 Webhooks:比轮询更高效的完成通知方式
  5. 验证输入:在调用 API 前检查提示词长度和图片格式

支持

需要 API 帮助?