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# Content Type : application/json
Timeout Setting : 15 seconds
After the task is completed, the system will send a POST request to your callBackUrl in the following format: Fallback Success Callback
{
"code" : 200 ,
"msg" : "Video generated successfully." ,
"data" : {
"taskId" : "veo_task_abcdef123456" ,
"promptJson" : "{\"aspectRatio\":\"16:9\",\"callBackUrl\":\"\\https://b7af305f36d6.ngrok-free.app/api/v1/modify/test\",\"enableFallback\":false,\"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 ]
} ,
"fallbackFlag" : false ,
"creditsConsumed" : 60 ,
}
} Status Code Description# Parameter Description# Parameter Type Required Description codeinteger Yes Callback status code indicating task processing result msgstring Yes Status message providing detailed status description data.taskIdstring Yes Task ID, consistent with the taskId returned when you submitted the task data.info.resultUrlsarray No Generated video URL array (returned only on success) data.info.originUrlsarray No Original video URL array (returned only on success) data.info.resolutionstring No Video resolution information (returned only on success), indicates the resolution of the generated video data.fallbackFlagboolean No Whether generated using fallback model. true means backup model was used, false means primary model was used
Status Code Details# Status Code Description 200 Success - Video generation task successfully 400 Client error - Prompt flagged for content policies, non-English prompt detected, failed to fetch image due to access limits, or unsafe image upload 422 Fallback failed - Request rejected by Flow despite fallback enabled (e.g., minor upload, prominent people upload, or content policy violations) 500 Internal error - Please try again later, internal error or timeout 501 Failed - Video generation task failed
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
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/pricing for pricing detailsError 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: 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
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 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: Veo3.1 Specific Notes# Veo3.1 Video Generation Features
Veo3.1 AI video generation functionality has the following characteristics: 1.
High-Quality Generation : Veo3.1 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.1 Video Details interface to periodically query task status, recommend querying every 30 seconds. 