Tài liệu API

Tài liệu API đầy đủ cho việc tạo video Veo 3.1 AI

Tổng quan

Veo 3.1 API cho phép bạn tạo video AI theo chương trình từ mô tả văn bản hoặc hình ảnh. RESTful API của chúng tôi được thiết kế đơn giản, mạnh mẽ và dễ dàng tích hợp vào ứng dụng của bạn.

URL cơ sở

https://veo3o1.com/api

Xác thực

Tất cả các yêu cầu API đều yêu cầu xác thực bằng khóa API. Bao gồm khóa API của bạn trong header Authorization:

Authorization: Bearer YOUR_API_KEY

Bạn có thể tạo khóa API từ bảng điều khiển tài khoản của mình.


Tạo video

Tạo video AI mới từ văn bản hoặc hình ảnh.

Endpoint

POST /generate-video

Nội dung yêu cầu

{
  "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
}

Tham số

Tham sốLoạiBắt buộcMô tả
generationTypestringLoại tạo: text_to_video hoặc image_to_video
promptstringMô tả video bạn muốn tạo
aspectRatiostringKhôngTỷ lệ khung hình video. Mặc định: auto
imageUrlstringCó điều kiệnBắt buộc nếu generationTypeimage_to_video
imageKeystringKhôngKhóa lưu trữ cho hình ảnh đã tải lên

Phản hồi

{
  "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"
  }
}

Ví dụ

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"
  }'

Lấy trạng thái video

Kiểm tra trạng thái của yêu cầu tạo video.

Endpoint

GET /video-status/{uuid}

Tham số

Tham sốLoạiBắt buộcMô tả
uuidstringUUID video từ yêu cầu tạo

Phản hồi

{
  "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
  }
}

Giá trị trạng thái

  • pending: Video đang trong hàng đợi xử lý
  • processing: Video đang được tạo
  • completed: Video đã sẵn sàng và có thể tải xuống
  • failed: Tạo thất bại (kiểm tra thông báo lỗi)

Tải lên hình ảnh

Tải lên hình ảnh để tạo video từ hình ảnh.

Endpoint

POST /upload-video-image

Yêu cầu

Sử dụng multipart/form-data để tải lên tệp hình ảnh.

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

Phản hồi

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

Định dạng được hỗ trợ

  • JPEG/JPG
  • PNG
  • WebP
  • Kích thước tệp tối đa: 50MB

Mã lỗi

Mô tả
0Thành công
1000Tham số không hợp lệ
1001Không đủ tín dụng
1002Xác thực thất bại
1003Vượt quá giới hạn tốc độ
5000Lỗi máy chủ

Ví dụ phản hồi lỗi

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

Thực hành tốt nhất

  1. Polling có trách nhiệm: Kiểm tra trạng thái video mỗi 5-10 giây, không liên tục
  2. Xử lý lỗi: Triển khai logic thử lại với backoff theo cấp số nhân
  3. Lưu cache kết quả: Lưu trữ video đã tạo để tránh tạo lại
  4. Sử dụng webhooks: Hiệu quả hơn polling cho thông báo hoàn thành
  5. Xác thực đầu vào: Kiểm tra độ dài prompt và định dạng hình ảnh trước khi gọi API

Hỗ trợ

Cần trợ giúp với API?