Skip to main content
POST
/
api
/
v1
/
veo
/
generate
Generate Veo3 Video
curl --request POST \
  --url https://api.veo3api.ai/api/v1/veo/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "A dog playing in a park",
  "imageUrls": [
    "http://example.com/image1.jpg"
  ],
  "model": "veo3",
  "watermark": "MyBrand",
  "callBackUrl": "http://your-callback-url.com/complete",
  "aspectRatio": "9:16",
  "seeds": 123456,
  "enableFallback": false
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "veo_task_abcdef123456"
  }
}
This document serves as the API documentation for Google Veo 3, which primarily includes two models: Veo 3 Quality API and Veo 3 Fast API. The primary difference between these models lies in their parameters, with ‘veo3’ corresponding to Veo 3 Quality and ‘veo3_fast’ representing the Fast model. Before diving into the specifics, here are some general details you should be aware of:
  1. Both Veo 3 Quality and Veo 3 Fast support text-to-video and image-to-video generation. The pricing for these APIs is significantly lower, being up to 70% more affordable than mainstream alternatives. For more details, please visit Billing Information.
  2. Currently, the concurrency is set to allow up to 20 new generation requests within a 10-second window. This quota is more than sufficient for most use cases.
  3. Veo 3 follows a strict censoring policy, which may result in some false positives where compliant content could be rejected. We’re awaiting an official fix from the team.
  4. You can obtain the results through two methods: via callback or by using the “get info” interface.
  5. We retain generated files for 14 days. After this period, files will be deleted, so it’s important to store them securely.
  6. If you encounter issues during development, it’s highly recommended to copy the relevant documentation and ask the AI for assistance. In most cases, this will help you resolve the issue faster. Should you need to contact us, feel free to reach out via Discord or Telegram, but remember to include the task ID to help us identify the issue.
  7. We also provide an n8n workflow for those who are less familiar with coding, making it easier to get started.

​
Intelligent Fallback (enableFallback)

We’ve added a fallback mechanismto the Veo 3 API. If Google’s strict content filters wrongly flag a normal prompt or image—triggering errors like**“public error minor upload,” “content policy violations,”or“public error prominent people upload”—you can now reroute the request through an alternative, more lenient Veo 3 channel.The fallback usesthe same Veo 3 model, with audio and the same quality;**only the path changes, greatly reducing false positives and boosting success rates.
PropertyTypeDefault
enableFallbackbooleanfalse
SettingenableFallback: trueinstructs the platform to reroute eligible failures to the secondary Veo 3 backend, raising completion rates for edge cases.

​
Limitations

  • 16 : 9 only – non‑conforming inputs are auto‑cropped before retry.
  • Billing – a successful fallback consumes a separate (higher‑priced) credit tier. See veo3api.ai/billing for the exact table.
Behaviour when disabledWithenableFallbackleft atfalse(default), the errors above surface as HTTP422responses and no additional credits are consumed.

​
Fallback Functionality

By setting the enableFallback parameter, you can enable intelligent fallback functionality. When the primary model encounters specific errors, the system will automatically switch to a backup model to continue generation, improving task success rates. Fallback Features:
  • Enabling Conditions: Set enableFallback: true, aspect ratio 16:9, and encounter specific errors
  • Applicable Errors: public error minor upload, content policy violations, public error prominent people upload
  • Image Requirements: Must be 16:9 ratio, otherwise automatic cropping will occur
  • Credit Calculation: Successful fallback has different credit consumption, please see https://veo3api.ai/billing for billing details.
  • Resolution: Fallback videos now default to 1080p resolution, but the Get 1080P Video endpoint may not work for fallback videos
Important Notes
  • Fallback functionality only takes effect in specific error scenarios
  • When fallback is not enabled, encountering fallback-eligible errors will return a 422 status code
  • While fallback videos now generate at 1080p resolution, the dedicated 1080p upgrade endpoint may not be compatible with fallback-generated videos

Authorizations

​
Authorization
string
header
required

All APIs require authentication via Bearer Token.

Get API Key:

  1. Visit API Key Management Page to get your API Key

Usage: Add to request header: Authorization: Bearer YOUR_API_KEY

Body

application/json
​
prompt
string
required

Text prompt describing the desired video content. Required for all generation modes.

  • Should be detailed and specific in describing video content
  • Can include actions, scenes, style and other information
  • For image-to-video, describe how you want the image to come alive
Example:

"A dog playing in a park"

​
imageUrls
string[]

Image URL list (used in image-to-video mode, only 1 image supported for now).

  • Must be valid image URLs
  • Images must be accessible to the API server
Example:
["http://example.com/image1.jpg"]
​
model
enum<string>
default:veo3

Select the model type to use.

  • veo3: Veo 3 Quality, supports both text-to-video and image-to-video generation
  • veo3_fast: Fast generation model, supports both text-to-video and image-to-video generation
Available options:
veo3,
veo3_fast
Example:

"veo3"

​
watermark
string

Watermark text.

  • Optional parameter
  • If provided, a watermark will be added to the generated video
Example:

"MyBrand"

​
aspectRatio
enum<string>
default:16:9

Video aspect ratio. Specifies the dimension ratio of the generated video. Available options:

  • 16:9: Landscape video format, supports 1080P HD video generation (Only 16:9 aspect ratio supports 1080P)
  • 9:16: Portrait video format, suitable for mobile short videos

Default value is 16:9.

Available options:
16:9,
9:16
Example:

"16:9"

​
seeds
integer

(Optional) Random seed parameter to control the randomness of the generated content. Value range: 10000-99999. The same seed will generate similar video content, different seeds will generate different content. If not provided, the system will assign one automatically.

Required range: 10000 <= x <= 99999
Example:

12345

​
callBackUrl
string

Completion callback URL.

  • Optional but recommended for production use
  • System will POST task completion status to this URL
  • Alternatively, use the Get Video Details endpoint to check status

📖 Detailed Callback Mechanism: See Video Generation Callbacks for callback format, status codes, best practices, and troubleshooting.

Example:

"http://your-callback-url.com/complete"

​
enableFallback
boolean
default:false

Enable fallback mechanism (default: false).

  • When enabled, fallback logic will be triggered for specific error conditions
  • Only works with 16:9 aspect ratio and specific error messages
  • Fallback generation uses different credit consumption (see https://veo3api.ai/billing)
  • Fallback videos now default to 1080p resolution, but the Get 1080P Video endpoint may not work for fallback videos
  • If original task credits > fallback model credits, the difference will be refunded
Example:

false

Response

Request successful

​
code
enum<integer>
required

Response status code

200 - Success - Request has been processed successfully

400 - 1080P is processing. It should be ready in 1-2 minutes. Please check back shortly.

401 - Unauthorized - Authentication credentials are missing or invalid

402 - Insufficient Credits - Account does not have enough credits to perform the operation

404 - Not Found - The requested resource or endpoint does not exist

422 - Validation Error - The request parameters failed validation checks, or Your request was rejected by Flow(Your request was rejected by Flow.). You may consider using our other fallback channels, which are likely to succeed. Please refer to the documentation.

429 - Rate Limited - Request limit has been exceeded for this resource

455 - Service Unavailable - System is currently undergoing maintenance

500 - Server Error - An unexpected error occurred while processing the request

501 - Generation Failed - Video generation task failed

505 - Feature Disabled - The requested feature is currently disabled

Available options:
200,
400,
401,
402,
404,
422,
429,
455,
500,
501,
505
​
msg
string
required

Error message when code != 200

Example:

"success"

​
data
object