When you submit a video generation task to the Veo3 API, you can set a callback address through the callBackUrl parameter. After the task is completed, the system will automatically push the results to your specified address.

Callback Mechanism Overview

The callback mechanism avoids the need for you to poll the API for task status, as the system will actively push task completion results to your server.

Callback Timing

The system will send callback notifications in the following situations:
  • Video generation task completed successfully
  • Video generation task failed
  • Error occurred during task processing

Callback Method

  • HTTP Method: POST
  • Content Type: application/json
  • Timeout Setting: 15 seconds

Callback Request Format

After the task is completed, the system will send a POST request to your callBackUrl in the following format:
{
  "code": 200,
  "msg": "Veo3 video generated successfully.",
  "data": {
    "taskId": "veo_task_abcdef123456",
    "info": {
      "resultUrls": ["http://example.com/video1.mp4"],
      "originUrls": ["http://example.com/original_video1.mp4"],
      "resolution": "1080p"
    },
    "fallbackFlag": false
  }
}

Status Code Description

code
integer
required
Callback status code indicating task processing result:
Status CodeDescription
200Success - Video generation task successfully
400Client error - Prompt violates content policies or other input errors
422Fallback failed - When fallback is not enabled and specific errors occur, returns error message format: Your request was rejected by Flow(original error message). You may consider using our other fallback channels, which are likely to succeed. Please refer to the documentation.
500Internal error - Please try again later, internal error or timeout
501Failed - Video generation task failed
msg
string
required
Status message providing detailed status description. Different status codes correspond to different error messages:400 Status Code Error Messages:
  • Your prompt was flagged by Website as violating content policies
  • Only English prompts are supported at this time
  • Failed to fetch the image. Kindly verify any access limits set by you or your service provider
  • Public error: unsafe image upload
422 Status Code Error Messages:
  • Your request was rejected by Flow(original error message). You may consider using our other fallback channels, which are likely to succeed. Please refer to the documentation.
Fallback Mechanism Description: When enableFallback is enabled and the following errors occur, the system will attempt to use the backup model:
  • public error minor upload
  • Your prompt was flagged by Website as violating content policies
  • public error prominent people upload
data.taskId
string
required
Task ID, consistent with the taskId returned when you submitted the task
data.info.resultUrls
array
Generated video URL array (returned only on success)
data.info.originUrls
array
Original video URL array (returned only on success), only has value when aspectRatio is not 16:9
data.info.resolution
string
Video resolution information (returned only on success), indicates the resolution of the generated video
data.fallbackFlag
boolean
Whether generated using fallback model. True means backup model was used, false means primary model was used

Fallback Functionality Description

The fallback functionality is an intelligent backup generation mechanism. When the primary model encounters specific errors, it automatically switches to a backup model to continue generation, improving task success rates.

Enabling Conditions

The fallback functionality requires the following conditions to be met simultaneously:
  1. enableFallback parameter is set to true in the request
  2. Aspect ratio is 16:9
  3. One of the following specific errors occurs:
    • public error minor upload
    • Your prompt was flagged by Website as violating content policies
    • public error prominent people upload

Fallback Limitations

  • Resolution: Fallback-generated videos are created in 1080p resolution by default and cannot be accessed via the Get 1080P Video endpoint
  • Image Requirements: If using image-to-video generation, images must be in 16:9 ratio, otherwise automatic cropping will occur
  • Credit Calculation: Successful fallback has different credit consumption, please see https://kie.ai/billing for billing details

Error Handling

  • Fallback Enabled: Automatically switch to backup model when specific errors occur, task continues execution
  • Fallback Not Enabled: Returns 422 status code when specific errors occur, suggesting to enable fallback functionality
The fallback functionality only takes effect in specific error scenarios. For other types of errors (such as insufficient credits, network issues, etc.), the fallback functionality will not be activated.

Callback Reception Examples

Here are example codes for receiving callbacks in popular programming languages:
const express = require('express');
const fs = require('fs');
const https = require('https');
const app = express();

app.use(express.json());

app.post('/veo3-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received Veo3 video generation callback:', {
    taskId: data.taskId,
    status: code,
    message: msg
  });
  
  if (code === 200) {
    // Video generation successful
    const { taskId, info, fallbackFlag } = data;
    const { resultUrls, originUrls, resolution } = info;
    
    console.log('Video generation successful!');
    console.log(`Task ID: ${taskId}`);
    console.log(`Generated video URLs: ${resultUrls}`);
    console.log(`Video resolution: ${resolution}`);
    console.log(`Using fallback model: ${fallbackFlag ? 'Yes' : 'No'}`);
    if (originUrls) {
      console.log(`Original video URLs: ${originUrls}`);
    }
    
    // Download generated video files
    resultUrls.forEach((url, index) => {
      if (url) {
        downloadFile(url, `veo3_generated_${taskId}_${index}.mp4`)
          .then(() => console.log(`Video ${index + 1} downloaded successfully`))
          .catch(err => console.error(`Video ${index + 1} download failed:`, err));
      }
    });
    
    // Download original video files (if exists)
    if (originUrls) {
      originUrls.forEach((url, index) => {
        if (url) {
          downloadFile(url, `veo3_original_${taskId}_${index}.mp4`)
            .then(() => console.log(`Original video ${index + 1} downloaded successfully`))
            .catch(err => console.error(`Original video ${index + 1} download failed:`, err));
        }
      });
    }
    
  } else {
    // Video generation failed
    console.log('Veo3 video generation failed:', msg);
    
    // Handle specific error types
    if (code === 400) {
      console.log('Client error - Check prompts and content policies');
    } else if (code === 422) {
      console.log('Fallback failed - Consider enabling fallback functionality (enableFallback: true)');
    } else if (code === 500) {
      console.log('Server internal error - Please try again later');
    } else if (code === 501) {
      console.log('Task failed - Video generation failed');
    }
  }
  
  // Return 200 status code to confirm callback received
  res.status(200).json({ code: 200, msg: 'success' });
});

// Helper function: Download file
function downloadFile(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();
          resolve();
        });
      } else {
        reject(new Error(`HTTP ${response.statusCode}`));
      }
    }).on('error', reject);
  });
}

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

Best Practices

Callback URL Configuration Recommendations

  1. Use HTTPS: Ensure callback URL uses HTTPS protocol to guarantee data transmission security
  2. Verify Source: Verify the legitimacy of request sources in callback processing
  3. Idempotent Processing: The same taskId may receive multiple callbacks, ensure processing logic is idempotent
  4. Quick Response: Callback processing should return 200 status code as soon as possible to avoid timeout
  5. Asynchronous Processing: Complex business logic should be processed asynchronously to avoid blocking callback response
  6. Timely Download: Video URLs have certain validity period, please download and save promptly
  7. Array Handling: resultUrls and originUrls are direct array formats that can be iterated directly
  8. English Prompts: Ensure using English prompts to avoid language-related errors

Important Reminders

  • Callback URL must be publicly accessible
  • Server must respond within 15 seconds, otherwise it will be considered timeout
  • After 3 consecutive retry failures, the system will stop sending callbacks
  • Only English prompts are supported, please ensure prompts use English
  • Please ensure the stability of callback processing logic to avoid callback failures due to exceptions
  • Properly handle content review errors to ensure input content complies with platform policies
  • resultUrls and originUrls return direct array formats that can be iterated directly
  • originUrls only has value when aspectRatio is not 16:9
  • Pay attention to image upload security checks to avoid uploading unsafe images

Troubleshooting

If you don’t receive callback notifications, please check the following:

Veo3 Specific Notes

Veo3 Video Generation Features

Veo3 AI video generation functionality has the following characteristics:
  1. High-Quality Generation: Veo3 provides high-quality AI video generation capabilities
  2. Multiple Aspect Ratio Support: Supports various aspect ratios, provides original video when not 16:9
  3. English Prompts: Only supports English prompts, please ensure input is in English
  4. Content Safety: Strict content review mechanism to ensure generated content is safe and compliant
  5. Flexible Output: resultUrls may contain multiple video files
  6. Original Preservation: When aspect ratio is not 16:9, original size video will be preserved

Alternative Solutions

If you cannot use the callback mechanism, you can also use polling:

Poll Query Results

Use the Get Veo3 Video Details interface to periodically query task status, recommend querying every 30 seconds.