Skip to content

API.md

Latest commit

 

History

History
324 lines (246 loc) · 7.76 KB

API.md

File metadata and controls

324 lines (246 loc) · 7.76 KB

Veo3 Video Generation API

Generate AI-powered videos from text prompts using Google's Veo3 technology.

Base URL

https://us-central1-cs-platform-306304.cloudfunctions.net/veo-proxy-anduin

Authentication

No authentication required. The API is publicly accessible.

Endpoints

Generate Video

Create a new video from a text description.

Endpoint: POST /

Request

Headers
Content-Type: application/json
Body Parameters
Parameter Type Required Description
email string Yes Your email address for tracking purposes
prompt string Yes Detailed description of the video you want to generate
tier string Yes Generation speed: "fast" or "normal"
tenant string No Optional identifier for your application (default: "default")
Example Request
{
  "email": "developer@example.com",
  "prompt": "A cinematic drone shot of a tropical beach at sunset with palm trees swaying in the breeze",
  "tier": "fast"
}

Response

Success (200 OK)
{
  "success": true,
  "url": "https://storage.googleapis.com/veo-proxy-videos/videos/abc123_1234567890.mp4",
  "recordId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Video generated successfully"
}
Field Type Description
success boolean Always true for successful generation
url string Direct URL to download/stream the generated video
recordId string Unique ID for this generation (for support purposes)
message string Success confirmation message
Error Responses

400 Bad Request - Invalid or missing parameters

{
  "error": "Missing required parameters",
  "required": ["email", "prompt", "tier"]
}

500 Internal Server Error - Generation failed

{
  "error": "Internal server error",
  "message": "Video generation timed out"
}

Quick Start Examples

cURL

curl -X POST https://us-central1-cs-platform-306304.cloudfunctions.net/veo-proxy-anduin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "prompt": "A time-lapse of flowers blooming in a garden",
    "tier": "fast"
  }'

JavaScript (Node.js/Browser)

async function generateVideo(prompt) {
  const response = await fetch('https://us-central1-cs-platform-306304.cloudfunctions.net/veo-proxy-anduin', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: 'your@email.com',
      prompt: prompt,
      tier: 'fast'
    })
  });

  const data = await response.json();
  
  if (data.success) {
    console.log('Video ready at:', data.url);
    return data.url;
  } else {
    throw new Error(data.error);
  }
}

// Usage
generateVideo('A cat playing piano').then(url => {
  console.log('Video URL:', url);
});

Python

import requests
import json

def generate_video(prompt, tier='fast'):
    """
    Generate a video from a text prompt
    
    Args:
        prompt: Text description of the video
        tier: 'fast' or 'normal' generation speed
    
    Returns:
        URL of the generated video
    """
    url = 'https://us-central1-cs-platform-306304.cloudfunctions.net/veo-proxy-anduin'
    
    payload = {
        'email': 'your@email.com',
        'prompt': prompt,
        'tier': tier
    }
    
    response = requests.post(url, json=payload)
    data = response.json()
    
    if response.status_code == 200:
        return data['url']
    else:
        raise Exception(f"Error: {data.get('error', 'Unknown error')}")

# Usage
video_url = generate_video('A futuristic cityscape with flying cars')
print(f"Video URL: {video_url}")

React Component

import { useState } from 'react';

function VideoGenerator() {
  const [prompt, setPrompt] = useState('');
  const [loading, setLoading] = useState(false);
  const [videoUrl, setVideoUrl] = useState('');
  const [error, setError] = useState('');

  const generateVideo = async () => {
    setLoading(true);
    setError('');
    
    try {
      const response = await fetch('https://us-central1-cs-platform-306304.cloudfunctions.net/veo-proxy-anduin', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          email: 'user@example.com',
          prompt: prompt,
          tier: 'fast'
        })
      });

      const data = await response.json();
      
      if (data.success) {
        setVideoUrl(data.url);
      } else {
        setError(data.error);
      }
    } catch (err) {
      setError('Failed to generate video');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <textarea 
        value={prompt}
        onChange={(e) => setPrompt(e.target.value)}
        placeholder="Describe your video..."
      />
      
      <button onClick={generateVideo} disabled={loading}>
        {loading ? 'Generating...' : 'Generate Video'}
      </button>
      
      {error && <p>Error: {error}</p>}
      
      {videoUrl && (
        <video controls src={videoUrl} style={{ width: '100%' }} />
      )}
    </div>
  );
}

Tier Comparison

Tier Model Generation Time Use Case
fast veo-3.0-fast-generate-preview ~30-60 seconds Quick previews, testing
normal veo-3.0-generate-preview ~2-5 minutes Production quality videos

Prompt Writing Tips

For best results, include these elements in your prompts:

  1. Camera movement: "Drone shot", "Panning left", "Zoom in"
  2. Scene details: "Sunset", "Foggy morning", "Night time"
  3. Subject actions: "Walking", "Flying", "Waves crashing"
  4. Style: "Cinematic", "Time-lapse", "Slow motion"
  5. Specific details: Colors, textures, atmosphere

Good Prompt Examples

✅ Detailed & Specific

"Cinematic drone shot following a red sports car driving along a winding coastal road at golden hour, waves crashing against cliffs below, shot in 4K with dramatic lighting"

✅ Clear Action

"Time-lapse of storm clouds gathering over a mountain range, lightning strikes illuminating the peaks, transitioning from day to night"

Poor Prompt Examples

❌ Too Vague

"A nice video of nature"

❌ Contradictory

"A sunny night scene with shadows"

Response Times

  • Fast tier: 30-90 seconds typical
  • Normal tier: 2-5 minutes typical
  • Maximum timeout: 9 minutes

The API uses long-polling, so your request will wait until the video is ready or timeout occurs.

Rate Limits

Currently no hard rate limits, but please:

  • Avoid parallel requests with the same email
  • Wait for each video to complete before requesting another
  • Use the tenant parameter to identify your application

Video Output

  • Format: MP4
  • Resolution: Varies by model (typically 720p-1080p)
  • Duration: Typically 2-5 seconds
  • Storage: Videos are permanently stored and accessible via the returned URL

Error Handling

The API returns standard HTTP status codes:

Status Code Meaning
200 Success - Video generated
400 Bad Request - Check your parameters
500 Server Error - Try again or use a simpler prompt

Always check the response body for detailed error messages.

Support

For issues or questions:

  • Include the recordId from your response when reporting issues
  • Check that your prompt is clear and descriptive
  • Try the "fast" tier first for testing

Terms of Use

  • Videos are generated using Google's Veo3 technology
  • Generated content must comply with Google's AI principles
  • Do not use for illegal, harmful, or deceptive purposes
  • Email addresses are logged for usage tracking