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"],
      "resolution": "1080p"
    },
    "fallbackFlag": false
  }
}

​
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
422Fallback Error - Your request was rejected by Flow(Your request was rejected by Flow.). You may consider using our other fallback channels, which are likely to succeed. Please refer to the documentation.
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
​
data.info.resolution
string
Video resolution (e.g., 720p, 1080p), returned when task is successful
​
data.fallbackFlag
boolean
Indicates whether this video was generated using fallback model. This field is present in both callback responses and query results.

​
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,
    fallbackUsed: data.fallbackFlag || false
  });
  
  if (code === 200) {
    // Task completed successfully
    const videoUrls = JSON.parse(data.info.resultUrls);
    const fallbackUsed = data.fallbackFlag;
    
    console.log('Video generation successful:', videoUrls);
    
    if (fallbackUsed) {
      console.log('⚠️  Video was generated using fallback model');
      // Handle fallback-specific logic (e.g., different credit calculation)
    } else {
      console.log('✅ Video was generated using original model');
    }
    
    // Process the generated video...
    
  } else if (code === 422) {
    // Fallback error occurred
    console.log('❌ Fallback error:', msg);
    
    // Handle fallback error case...
    
  } else {
    // Other task failures
    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.