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
Callback Request Format
After the task is completed, the system will send a POST request to yourcallBackUrl in the following format:
Status Code Description
Callback status code indicating task processing result:
| Status Code | Description |
|---|---|
| 200 | Success - Video generation task successfully |
| 400 | Client error - Prompt violates content policies or other input errors |
| 422 | Fallback failed - When fallback is not enabled and specific errors occur, returns error message format: Your request was rejected by Flow(original error message). You may consider using our other fallback channels, which are likely to succeed. Please refer to the documentation. |
| 500 | Internal error - Please try again later, internal error or timeout |
| 501 | Failed - Video generation task failed |
Status message providing detailed status description. Different status codes correspond to different error messages:400 Status Code Error Messages:
- 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
- Your request was rejected by Flow(original error message). You may consider using our other fallback channels, which are likely to succeed. Please refer to the documentation.
enableFallback is enabled and the following errors occur, the system will attempt to use the backup model:- public error minor upload
- Your prompt was flagged by Website as violating content policies
- public error prominent people upload
Task ID, consistent with the taskId returned when you submitted the task
Generated video URL array (returned only on success)
Original video URL array (returned only on success), only has value when aspectRatio is not 16:9
Video resolution information (returned only on success), indicates the resolution of the generated video
Whether generated using fallback model. True means backup model was used, false means primary model was used
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:enableFallbackparameter is set totruein the request- Aspect ratio is
16:9 - 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/billing for billing details
Error 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:- 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
- 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:Network Connection Issues
Network Connection Issues
- Confirm callback URL is accessible from public network
- Check firewall settings to ensure inbound requests are not blocked
- Verify domain name resolution is correct
Server Response Issues
Server Response Issues
- Ensure server returns HTTP 200 status code within 15 seconds
- Check error information in server logs
- Verify interface path and HTTP method are correct
Content Format Issues
Content Format Issues
- Confirm received POST request body is JSON format
- Check if Content-Type is application/json
- Verify JSON parsing is correct
- Correctly handle resultUrls and originUrls array formats
Video Processing Issues
Video Processing Issues
- Confirm video URLs are accessible
- Check video download permissions and network connection
- Verify video save path and permissions
- Pay attention to video URL validity period limitations
- Backup videos to long-term storage system promptly
Content Review Issues
Content Review Issues
- Review content review error messages
- Ensure prompts use English
- Ensure input images don’t contain inappropriate content
- Check if prompts comply with platform content policies
- Avoid using sensitive or violating descriptive words
- Ensure image uploads are safe and in correct format
Generation Quality Issues
Generation Quality Issues
- Check generated video quality and resolution
- Verify video duration meets expectations
- Evaluate generated video quality and style
- Ensure video content meets expectations
- If originUrls exist, compare differences between original and generated videos
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
- English Prompts: Only supports English prompts, please ensure input is in English
- 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.
