API Reference

Overview

The Veo 3.1 API allows you to programmatically generate AI videos from text descriptions or images. Our RESTful API is designed to be simple, powerful, and easy to integrate into your applications.

Base URL

https://veo3o1.com/api

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can generate API keys from your account dashboard.

Generate Video

Create a new AI video from text or image.

Endpoint

POST /generate-video

Request Body

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

Parameters

Parameter	Type	Required	Description
`generationType`	string	Yes	Type of generation: `text_to_video` or `image_to_video`
`prompt`	string	Yes	Description of the video you want to generate
`aspectRatio`	string	No	Video aspect ratio. Default: `auto`
`imageUrl`	string	Conditional	Required if `generationType` is `image_to_video`
`imageKey`	string	No	Storage key for uploaded images

Response

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

Example

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

Check the status of a video generation request.

Endpoint

GET /video-status/{uuid}

Parameters

Parameter	Type	Required	Description
`uuid`	string	Yes	Video UUID from generation request

Response

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

Status Values

pending: Video is queued for processing
processing: Video is being generated
completed: Video is ready and available for download
failed: Generation failed (check error message)

Upload Image

Upload an image for image-to-video generation.

Endpoint

POST /upload-video-image

Request

Use multipart/form-data to upload image file.

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

Response

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

Supported Formats

JPEG/JPG
PNG
WebP
Maximum file size: 50MB

Error Codes

Code	Description
0	Success
1000	Invalid parameters
1001	Insufficient credits
1002	Authentication failed
1003	Rate limit exceeded
5000	Server error

Error Response Example

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

Rate Limits

Free tier: 10 requests/hour
Starter: 100 requests/hour
Pro: 500 requests/hour
Enterprise: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1697472000

SDKs & Libraries

We provide official SDKs for popular programming languages:

JavaScript/TypeScript: npm install @veo3o1/sdk
Python: pip install veo3o1
Go: go get github.com/veo3o1/go-sdk

JavaScript Example

import { Veo3o1 } from '@veo3o1/sdk';

const client = new Veo3o1('YOUR_API_KEY');

const video = await client.generateVideo({
  generationType: 'text_to_video',
  prompt: 'A beautiful sunset over the ocean',
  aspectRatio: '16:9'
});

console.log('Video UUID:', video.uuid);

Webhooks

Configure webhooks to receive notifications when videos are completed.

Setup

Go to API Settings
Enter your webhook URL
Select events to receive

Event Types

video.completed: Video generation completed successfully
video.failed: Video generation failed

Webhook Payload

{
  "event": "video.completed",
  "uuid": "video-uuid-123",
  "videoUrl": "https://...",
  "timestamp": "2025-10-16T10:05:00Z"
}

Best Practices

Poll responsibly: Check video status every 5-10 seconds, not continuously
Handle errors: Implement retry logic with exponential backoff
Cache results: Store generated videos to avoid regenerating
Use webhooks: More efficient than polling for completion
Validate inputs: Check prompt length and image formats before API calls

Support

Need help with the API?

On this page