Veo3.1 API Quickstart

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

Overview

Veo3.1 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

Visit API Key Management Page
Register or log in to your account
Generate a new API Key
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

async function generateVideo() {
  try {
    const response = await fetch('https://api.kie.ai/api/v1/veo/generate', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        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
      })
    });
    
    const data = await response.json();
    
    if (response.ok && data.code === 200) {
      console.log('Task submitted:', data);
      console.log('Task ID:', data.data.taskId);
      return data.data.taskId;
    } else {
      console.error('Request failed:', data.msg || 'Unknown error');
      return null;
    }
  } catch (error) {
    console.error('Error:', error.message);
    return null;
  }
}

generateVideo();

Image-to-Video Example

const response = await fetch('https://api.kie.ai/api/v1/veo/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
  })
});

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 fetch(`https://api.kie.ai/api/v1/veo/record-info?taskId=${taskId}`, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    const result = await response.json();
    
    if (response.ok && result.code === 200) {
      const data = result.data;
      
      switch(data.successFlag) {
        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:', result.msg);
          break;
      }
      
      return null;
    } else {
      console.error('Status check failed:', result.msg || 'Unknown error');
      return null;
    }
  } catch (error) {
    console.error('Status check failed:', error.message);
    return null;
  }
}

// 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

successFlag	Description
0	Generating - Task is currently being processed
1	Success - Task completed successfully
2	Failed - Task generation failed
3	Generation 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 fetch(`https://api.kie.ai/api/v1/veo/get-1080p-video?taskId=${taskId}`, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    const data = await response.json();
    
    if (response.ok && data.code === 200) {
      console.log('1080P video:', data);
      return data;
    } else {
      console.error('Failed to get 1080P video:', data.msg || 'Unknown error');
      return null;
    }
  } catch (error) {
    console.error('Failed to get 1080P video:', error.message);
    return null;
  }
}

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.

Callback Handling (Recommended)

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-1-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 fs = require('fs');
const https = require('https');

class Veo31Client {
  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 fetch(`${this.baseUrl}/api/v1/veo/generate`, {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify(payload)
      });
      
      const data = await response.json();
      
      if (response.ok && data.code === 200) {
        return data.data.taskId;
      } else {
        throw new Error(`Video generation failed: ${data.msg || 'Unknown error'}`);
      }
    } catch (error) {
      throw new Error(`Video generation failed: ${error.message}`);
    }
  }

  // Check status
  async getStatus(taskId) {
    try {
      const response = await fetch(`${this.baseUrl}/api/v1/veo/record-info?taskId=${taskId}`, {
        method: 'GET',
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      });
      
      const data = await response.json();
      
      if (response.ok && data.code === 200) {
        return data.data;
      } else {
        throw new Error(`Status check failed: ${data.msg || 'Unknown error'}`);
      }
    } catch (error) {
      throw new Error(`Status check failed: ${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.successFlag}`);
      
      if (status.successFlag === 1) {
        return JSON.parse(status.resultUrls);
      } else if (status.successFlag === 2 || status.successFlag === 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 Veo31Client('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

How long does generation take?

Typically 2-5 minutes, depending on video complexity and server load. Use veo3_fast model for faster generation speed.

What image formats are supported?

Supports common image formats including JPG, PNG, WebP, etc. Ensure image URLs are accessible to the API server.

How to get better video quality?

Use detailed and specific prompts
Choose veo3 standard model over fast model
For 16:9 videos, get 1080P high-definition version

Do video URLs have expiry dates?

Generated video URLs have certain validity periods. It’s recommended to download and save them to your storage system promptly.

How to handle generation failures?

Check if prompts violate content policies
Confirm image URLs are accessible
Review specific error messages
Contact technical support if necessary

How to generate a Veo 3.1 video longer than 8 seconds?

Clips made directly in VEO 3.1 are limited to 8 seconds. Anything longer has been edited externally after export.

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

​Overview

Text-to-Video

Image-to-Video

HD Support

Real-time Callbacks

​Step 1: Get Your API Key

​Step 2: Basic Authentication

​Step 3: Your First Video Generation

​Text-to-Video Example

​Image-to-Video Example

​Step 4: Check Task Status

​Polling Method

​Status Descriptions

​Step 5: Get HD Video (Optional)

​Callback Handling (Recommended)

​Complete Example: From Generation to Download

​Best Practices

Optimize Prompts

Choose Models Wisely

Handle Exceptions

Resource Management

​Frequently Asked Questions

​Next Steps

API Reference

Callback Handling

Get Details

Overview

Step 1: Get Your API Key

Step 2: Basic Authentication

Step 3: Your First Video Generation

Text-to-Video Example

Image-to-Video Example

Step 4: Check Task Status

Polling Method

Status Descriptions

Step 5: Get HD Video (Optional)

Callback Handling (Recommended)

Complete Example: From Generation to Download

Best Practices

Frequently Asked Questions

Next Steps