Welcome to Veo3 API! This guide will help you quickly get started with our high-quality AI video generation service.

​
Overview

Veo3 API is a powerful AI video generation platform that supports:

Text-to-Video

Generate high-quality videos through descriptive text prompts

Image-to-Video

Bring static images to life, creating engaging videos

HD Support

Support for generating 1080P high-definition videos (16:9 aspect ratio)

Real-time Callbacks

Automatically push results to your server when tasks complete

​
Step 1: Get Your API Key

  1. Visit API Key Management Page
  2. Register or log in to your account
  3. Generate a new API Key
  4. Safely store your API Key
Please keep your API Key secure and do not expose it in public code repositories. If you suspect it has been compromised, reset it immediately.

​
Step 2: Basic Authentication

All API requests need to include your API Key in the request headers: 
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
API Base URL: https://api.kie.ai

​
Step 3: Your First Video Generation

​
Text-to-Video Example

const axios = require('axios');

async function generateVideo() {
  try {
    const response = await axios.post('https://api.kie.ai/api/v1/veo/generate', {
      prompt: "A cute cat playing in a garden on a sunny day, high quality",
      model: "veo3",
      aspectRatio: "16:9",
      callBackUrl: "https://your-website.com/callback" // Optional
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Task submitted:', response.data);
    const taskId = response.data.data.taskId;
    console.log('Task ID:', taskId);
    
    return taskId;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

generateVideo();

​
Image-to-Video Example

const response = await axios.post('https://api.kie.ai/api/v1/veo/generate', {
  prompt: "Make the person in this image wave and smile, with background gently swaying",
  imageUrls: ["https://your-domain.com/image.jpg"],
  model: "veo3",
  aspectRatio: "16:9"
}, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

​
Step 4: Check Task Status

Video generation typically takes a few minutes. You can get results through polling or callbacks.

​
Polling Method

async function checkStatus(taskId) {
  try {
    const response = await axios.get(`https://api.kie.ai/api/v1/veo/record-info?taskId=${taskId}`, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    const { status, msg, data } = response.data;
    
    switch(data.status) {
      case 0:
        console.log('Generating...');
        break;
      case 1:
        console.log('Generation successful!');
        console.log('Video URLs:', JSON.parse(data.resultUrls));
        return data;
      case 2:
      case 3:
        console.log('Generation failed:', msg);
        break;
    }
    
    return null;
  } catch (error) {
    console.error('Status check failed:', error.response?.data || error.message);
  }
}

// Usage example
async function waitForCompletion(taskId) {
  let result = null;
  while (!result) {
    result = await checkStatus(taskId);
    if (!result) {
      await new Promise(resolve => setTimeout(resolve, 30000)); // Wait 30 seconds
    }
  }
  return result;
}

​
Status Descriptions

Status CodeDescription
0Generating - Task is currently being processed
1Success - Task completed successfully
2Failed - Task generation failed
3Generation Failed - Task created successfully but generation failed

​
Step 5: Get HD Video (Optional)

If you use 16:9 aspect ratio to generate videos, you can get the 1080P high-definition version: 
async function get1080pVideo(taskId) {
  try {
    const response = await axios.get(`https://api.kie.ai/api/v1/veo/get-1080p-video?taskId=${taskId}`, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    console.log('1080P video:', response.data);
    return response.data;
  } catch (error) {
    console.error('Failed to get 1080P video:', error.response?.data || error.message);
  }
}
Note: 1080P video requires additional processing time. It’s recommended to wait a few minutes after the original video generation is completed before calling this endpoint.
Compared to polling, callback mechanism is more efficient. Set the callBackUrl parameter, and the system will automatically push results when tasks complete: 
const express = require('express');
const app = express();

app.use(express.json());

app.post('/veo3-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received callback:', {
    taskId: data.taskId,
    status: code,
    message: msg
  });
  
  if (code === 200) {
    // Video generation successful
    const videoUrls = JSON.parse(data.info.resultUrls);
    console.log('Video generation successful:', videoUrls);
    
    // Process the generated videos...
    downloadAndProcessVideos(videoUrls);
  } else {
    console.log('Video generation failed:', msg);
  }
  
  // Return 200 to confirm callback received
  res.status(200).json({ status: 'received' });
});

app.listen(3000, () => {
  console.log('Callback server running on port 3000');
});

​
Complete Example: From Generation to Download

const axios = require('axios');
const fs = require('fs');
const https = require('https');

class Veo3Client {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.kie.ai';
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    };
  }

  // Generate video
  async generateVideo(prompt, options = {}) {
    const payload = {
      prompt,
      model: options.model || 'veo3',
      aspectRatio: options.aspectRatio || '16:9',
      ...options
    };

    try {
      const response = await axios.post(`${this.baseUrl}/api/v1/veo/generate`, payload, {
        headers: this.headers
      });
      
      return response.data.data.taskId;
    } catch (error) {
      throw new Error(`Video generation failed: ${error.response?.data?.msg || error.message}`);
    }
  }

  // Check status
  async getStatus(taskId) {
    try {
      const response = await axios.get(`${this.baseUrl}/api/v1/veo/record-info?taskId=${taskId}`, {
        headers: this.headers
      });
      
      return response.data.data;
    } catch (error) {
      throw new Error(`Status check failed: ${error.response?.data?.msg || error.message}`);
    }
  }

  // Wait for completion
  async waitForCompletion(taskId, maxWaitTime = 600000) { // Default max wait 10 minutes
    const startTime = Date.now();
    
    while (Date.now() - startTime < maxWaitTime) {
      const status = await this.getStatus(taskId);
      
      console.log(`Task ${taskId} status: ${status.status}`);
      
      if (status.status === 1) {
        return JSON.parse(status.resultUrls);
      } else if (status.status === 2 || status.status === 3) {
        throw new Error('Video generation failed');
      }
      
      await new Promise(resolve => setTimeout(resolve, 30000)); // Wait 30 seconds
    }
    
    throw new Error('Task timeout');
  }

  // Download video
  async downloadVideo(url, filename) {
    return new Promise((resolve, reject) => {
      const file = fs.createWriteStream(filename);
      
      https.get(url, (response) => {
        if (response.statusCode === 200) {
          response.pipe(file);
          file.on('finish', () => {
            file.close();
            console.log(`Video downloaded: ${filename}`);
            resolve(filename);
          });
        } else {
          reject(new Error(`Download failed: HTTP ${response.statusCode}`));
        }
      }).on('error', reject);
    });
  }

  // Complete workflow
  async generateAndDownload(prompt, filename = 'video.mp4', options = {}) {
    try {
      console.log('Starting video generation...');
      const taskId = await this.generateVideo(prompt, options);
      console.log(`Task submitted: ${taskId}`);
      
      console.log('Waiting for completion...');
      const videoUrls = await this.waitForCompletion(taskId);
      console.log('Video generation completed!');
      
      console.log('Starting video download...');
      await this.downloadVideo(videoUrls[0], filename);
      
      return { taskId, videoUrls, filename };
    } catch (error) {
      console.error('Error:', error.message);
      throw error;
    }
  }
}

// Usage example
async function main() {
  const client = new Veo3Client('YOUR_API_KEY');
  
  try {
    const result = await client.generateAndDownload(
      'A cute cat playing in a garden on a sunny day, high quality',
      'cute_cat.mp4',
      { aspectRatio: '16:9' }
    );
    
    console.log('Complete!', result);
  } catch (error) {
    console.error('Generation failed:', error.message);
  }
}

main();

​
Best Practices

Optimize Prompts

  • Use detailed and specific descriptions
  • Include actions, scenes, and style information
  • Avoid vague or contradictory descriptions

Choose Models Wisely

  • veo3: Quality model, higher quality
  • veo3_fast: Fast model, quicker generation

Handle Exceptions

  • Implement retry mechanisms
  • Handle network and API errors
  • Log errors for debugging

Resource Management

  • Download and save videos promptly
  • Control concurrent request numbers reasonably
  • Monitor API usage quotas

​
Frequently Asked Questions

​
Next Steps

API Reference

View complete API parameters and response formats

Callback Handling

Learn how to handle task completion callbacks

Get Details

Learn how to query task status and results
If you encounter any issues during usage, please contact our technical support: support@kie.ai