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
  • Retry Mechanism: Retry 3 times after failure, with intervals of 1 minute, 5 minutes, and 15 minutes respectively

​
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"]
    }
  }
}

​
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
500Internal error - Please try again later, internal error or timeout
501Failed - Video generation task failed
​
msg
string
required
Status message providing detailed status description. When code is 400, possible error messages include:
  • 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
​
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

​
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 } = data;
    const { resultUrls, originUrls } = info;
    
    console.log('Video generation successful!');
    console.log(`Task ID: ${taskId}`);
    console.log(`Generated video URLs: ${resultUrls}`);
    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 === 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.