Skip to main content
⚠️ This documentation is for legacy custom API, not recommendedPlease see new version: Veo-3.1 Best Practices

​
Prompt Writing Guide

Writing high-quality prompts is key to obtaining excellent videos. Below are detailed explanations of each element:

​
Prompt Structure

  • Subject Description
  • Actions & Behaviors
  • Environment & Scene
  • Camera Movement
  • Visual Style
Clearly describe the main object or character in the videoGood examples:
  • “An orange kitten”
  • “A young girl in a red dress”
  • “A silver sports car”
Avoid:
  • “Something”
  • “Some animals”
Specifically describe the subject’s actions and behaviorsGood examples:
  • “Walking slowly”
  • “Running quickly”
  • “Dancing gracefully”
Avoid:
  • “Moving”
  • “Doing something”
Describe the background and environment in detailGood examples:
  • “A sunny garden”
  • “Rainy city streets at night”
  • “A beach at sunset”
Avoid:
  • “Some place”
  • “Outside”
Describe the camera movementGood examples:
  • “Camera following”
  • “Overhead view”
  • “360-degree rotation”
Optional element Specify the desired visual styleGood examples:
  • “4K high definition, cinematic quality”
  • “Animation style”
  • “Vintage film aesthetic”
Optional element

​
Excellent Prompt Examples

​
Prompt Enhancement Feature

Enabling enhance_prompt allows AI to automatically optimize your prompt, improving generation quality

​
When to Use Prompt Enhancement

  • First-time API usage
  • Simple prompts
  • Want better results
  • Unsure how to describe

​
Can Disable

  • Need precise control
  • Already have comprehensive prompts
  • Specific style requirements
  • Technical descriptions

​
Using Reference Images

​
Image Requirements

RequirementDescription
FormatJPG, PNG, WebP
SizeMax 10MB per image
QuantityMax 5 images
ResolutionRecommended 1024x1024 or higher
ContentClear, relevant reference material

​
Usage Tips

1 Choose High-Quality Images Use clear, high-resolution images as references 2 Maintain Consistent Style Multiple images should maintain visual style consistency 3 Prioritize Relevance Select reference images most relevant to the target video 4 Avoid Conflicts Image content should not conflict with text descriptions

​
Polling Strategy

import time
import math

def exponential_backoff_polling(client, task_id, initial_interval=5, max_interval=60):
    """
    Exponential backoff polling strategy
    """
    interval = initial_interval
    attempt = 0
    
    while True:
        try:
            status_data = client.get_status(task_id)
            status = status_data.get('status')
            
            if status == 'completed':
                return status_data['result']
            elif status == 'failed':
                raise Exception(f"Generation failed: {status_data.get('error')}")
            
            # Exponential backoff
            time.sleep(interval)
            attempt += 1
            interval = min(initial_interval * math.pow(1.5, attempt), max_interval)
            
        except Exception as e:
            print(f"Polling error: {e}")
            time.sleep(interval)

​
Polling Parameter Recommendations

  • Initial interval: 5 seconds
  • Max interval: 60 seconds
  • Backoff factor: 1.5
  • Max wait: 30 minutes

​
Error Handling

​
Retry Strategy

def retry_with_backoff(func, max_retries=3, backoff_factor=2):
    """
    Retry mechanism with backoff
    """
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            
            wait_time = backoff_factor ** attempt
            print(f"Failed, retrying in {wait_time} seconds...")
            time.sleep(wait_time)

​
Common Error Handling

  • Network Errors
  • API Errors
  • Task Failures
try:
    result = client.submit_task(prompt)
except requests.exceptions.ConnectionError:
    print("Network connection failed, please check network")
except requests.exceptions.Timeout:
    print("Request timeout, please retry later")

try:
    result = client.submit_task(prompt)
except Exception as e:
    if "QUOTA_EXCEEDED" in str(e):
        print("Quota exceeded")
    elif "INVALID_PROMPT" in str(e):
        print("Invalid prompt")

status = client.get_status(task_id)
if status['status'] == 'failed':
    error_info = status.get('error', {})
    print(f"Task failed: {error_info.get('message')}")
    # Can try resubmitting

​
Performance Optimization

​
Batch Processing

When generating multiple videos, batch processing is recommended: 
async def batch_process_videos(prompts, max_concurrent=5):
    """
    Batch process video generation
    """
    semaphore = asyncio.Semaphore(max_concurrent)
    
    async def process_one(prompt):
        async with semaphore:
            return await client.submit_and_wait(prompt)
    
    tasks = [process_one(prompt) for prompt in prompts]
    return await asyncio.gather(*tasks)

​
Resource Management

Note concurrency limit: Maximum 10 tasks simultaneously

​
Cost Optimization

​
Model Selection Strategy

def choose_model(requirements):
    """
    Intelligently select model based on requirements
    """
    if requirements.get('need_fast'):
        return 'veo3-fast'
    elif requirements.get('high_quality'):
        return 'veo3-pro'
    elif requirements.get('precise_control'):
        return 'veo3-pro-frames'
    else:
        return 'veo3'  # Default to standard version

​
Testing Recommendations

Use veo3 or veo3-fast for testing during development, select appropriate models for production based on needs

​
Monitoring and Logging

import logging
from datetime import datetime

class VEOLogger:
    def __init__(self):
        self.logger = logging.getLogger('veo_api')
        
    def log_task_submission(self, task_id, prompt, model):
        self.logger.info(f"Task submitted: {task_id}")
        self.logger.debug(f"Prompt: {prompt[:50]}...")
        self.logger.debug(f"Model: {model}")
        
    def log_task_completion(self, task_id, duration, video_url):
        self.logger.info(f"Task completed: {task_id}")
        self.logger.info(f"Duration: {duration}s")
        self.logger.debug(f"Video URL: {video_url}")

​
Monitoring Metrics

  • Task success rate
  • Average generation time
  • API response time
  • Error rate statistics
  • Cost tracking