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

​
Callback Mechanism Overview

The callback mechanism eliminates the need to poll the API for task status. The system will proactively 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
  • Errors occurred during task processing

​
Callback Method

  • HTTP Method: POST
  • Content Type: application/json
  • Timeout Setting: 15 seconds
  • Retry Mechanism: 3 retries after failure, with intervals of 1 minute, 5 minutes, and 15 minutes

​
Callback Request Format

When a task is completed, the system will send a POST request in the following format to your callBackUrl:

{
  "code": 200,
  "msg": "Veo3 video generated successfully.",
  "data": {
    "taskId": "veo_task_abcdef123456",
    "info": {
      "resultUrls": "[http://example.com/video1.mp4]",
      "originUrls": ["http://example.com/original1.mp4"]
    }
  }
}

​
Status Code Description

​
code
integer
required

Callback status code indicating the task processing result:

Status CodeDescription
200Success - Video generation task completed successfully
400Error - Prompt violates content policies or other input errors
500Internal Error - Server internal error or timeout
501Failed - Video generation task failed
​
msg
string
required

Status message providing more detailed status description

​
data.taskId
string
required

Task ID, consistent with the taskId returned when you submitted the task

​
data.info.resultUrls
string

Generated video URL, returned when successful

​
data.info.originUrls
array

Original video link array, only has value when aspectRatio is not 16:9

​
Callback Reception Examples

The following are example codes for receiving callbacks in common programming languages:

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) {
    // Task completed successfully
    const videoUrls = JSON.parse(data.info.resultUrls);
    console.log('Video generation successful:', videoUrls);
    
    // Process the generated video...
    
  } else {
    // Task failed
    console.log('Task failed:', msg);
    
    // Handle failure case...
  }
  
  // Return 200 status code to confirm callback received
  res.status(200).json({ status: 'received' });
});

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

​
Best Practices

​
Callback URL Configuration Recommendations

  1. Use HTTPS: Ensure callback URLs use 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 a 200 status code as quickly as possible to avoid timeouts
  5. Asynchronous Processing: Complex business logic should be processed asynchronously to avoid blocking callback responses

​
Important Notes

  • Callback URL must be a publicly accessible address
  • Server must respond within 15 seconds, otherwise it will be considered a timeout
  • If 3 consecutive retries fail, the system will stop sending callbacks
  • Please ensure the stability of callback processing logic to avoid callback failures due to exceptions

​
Troubleshooting

If you are not receiving callback notifications, please check the following:

​
Alternative Solutions

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

Polling for Results

Use the Get Video Details endpoint to periodically query task status. We recommend querying every 30 seconds.