Veo3.1 Video Generation Callbacks

The system will call this callback to notify results when video generation is completed

When you submit a video generation task to the Veo3.1 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.

Webhook Security: To ensure the authenticity and integrity of callback requests, we strongly recommend implementing webhook signature verification. See our Webhook Verification Guide for detailed implementation steps.

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:

Success Callback

Failure Callback

{
  "code": 200,
  "msg": "Video generated successfully.",
  "data": {
    "taskId": "veo_task_abcdef123456",
    "promptJson": "{\"aspectRatio\":\"16:9\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"enableTranslation\":true,\"model\":\"veo3_fast\",\"prompt\":\"cat\"}",
    "info": {
      "resultUrls": ["http://example.com/video1.mp4"],
      "originUrls": ["http://example.com/original_video1.mp4"],
      "resolution": "1080p",
      "seeds": [21753],
      "media_ids": ["e5895558-a627-408a-845c-22e33a775670"],
      "has_audio_list": [true]
    },
    "creditsConsumed": 60
  }
}

Status Code Description

Parameter Description

Parameter	Type	Required	Description
`code`	integer	Yes	Callback status code indicating task processing result
`msg`	string	Yes	Status message providing detailed status description
`data.taskId`	string	Yes	Task ID, consistent with the `taskId` returned when you submitted the task
`data.info.resultUrls`	array	No	Generated video URL array (returned only on success)
`data.info.originUrls`	array	No	Original video URL array (returned only on success)
`data.info.resolution`	string	No	Video resolution information (returned only on success), indicates the resolution of the generated video

Status Code Details

Status Code	Description
200	Success - Video generation task successfully
400	Client error - Prompt flagged for content policies, failed to fetch image due to access limits, or unsafe image upload
500	Internal error - Please try again later, internal error or timeout
501	Failed - Video generation task failed

Callback Reception Examples

Here are example codes for receiving callbacks in popular programming languages:

Node.js

Python

PHP

Best Practices

Callback URL Configuration Recommendations

Use HTTPS: Ensure callback URL uses HTTPS protocol to guarantee data transmission security

Verify Source: Verify the legitimacy of request sources in callback processing

Idempotent Processing: The same taskId may receive multiple callbacks, ensure processing logic is idempotent

Quick Response: Callback processing should return 200 status code as soon as possible to avoid timeout

Asynchronous Processing: Complex business logic should be processed asynchronously to avoid blocking callback response

Timely Download: Video URLs have certain validity period, please download and save promptly

Array Handling: resultUrls and originUrls are direct array formats that can be iterated directly

Prompt Language: Prompts in any language are accepted.

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

Prompts in any language are accepted.

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 aspect_ratio 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:

Network Connection Issues

Server Response Issues

Content Format Issues

Video Processing Issues

Content Review Issues

Generation Quality Issues

Veo3.1 Specific Notes

Veo3.1 Video Generation Features

Veo3.1 AI video generation functionality has the following characteristics:

High-Quality Generation: Veo3.1 provides high-quality AI video generation capabilities

Multiple Aspect Ratio Support: Supports various aspect ratios, provides original video when not 16:9

Prompt Language: Prompts in any language are accepted.

Content Safety: Strict content review mechanism to ensure generated content is safe and compliant

Flexible Output: resultUrls may contain multiple video files

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.1 Video Details interface to periodically query task status, recommend querying every 30 seconds.

Veo3.1 Video Generation Callbacks

Callback Mechanism Overview#

Callback Timing#

Callback Method#

Callback Request Format#

Status Code Description#

Parameter Description#

Status Code Details#

Callback Reception Examples#

Best Practices#

Troubleshooting#

Veo3.1 Specific Notes#

Alternative Solutions#

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Status Code Description

Parameter Description

Status Code Details

Callback Reception Examples

Best Practices

Troubleshooting

Veo3.1 Specific Notes

Alternative Solutions