When a video generation task is complete, the system will send the results to your provided callback URL via a POST request
When you submit a video modification task to the Luma API, you can use the callBackUrl parameter to set up a callback URL. When the task is complete, the system will automatically push the results to your specified address.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.
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 modification task successfully completed
Video modification task failed
Error occurred during task processing
Callback Method#
Content Type: application/json
Timeout Setting: 15 seconds
callBackUrl with the following format:Generation Failure Callback
{
"code": 200,
"msg": "Modification record generated successfully.",
"data": {
"taskId": "774d9a7dd608a0e49293903095e45a4c",
"promptJson": "{\"callBackUrl\":\"https://b7af305f36d6.ngrok-free.app/api/v1/modify/test\",\"prompt\":\"A futuristic cityscape at night with towering glass spires reaching into a starry sky. Blue and purple neon lights illuminate the buildings while flying vehicles glide silently between the structures. Holographic advertisements flicker and change on building facades.\",\"videoUrl\":\"https://tempfile.aiquickdraw.com/kieai/file/veo3-video/1755074605154fqb0m8ge.mp4\",\"waterMark\":\"\"}",
"resultUrls": [
"https://tempfile.aiquickdraw.com/l/f782018c-6be4-4990-96ba-7231cd5a39e7.mp4"
]
}
}
Status Code Explanation#
code (integer, required)#
Callback status code indicating the task processing result:| Status Code | Description |
|---|
| 200 | Success - Video modification completed successfully |
| 500 | Failure - Video modification task failed |
msg (string, required)#
Status message providing detailed status descriptiondata.taskId (string, required)#
Task ID, consistent with the taskId returned when you submitted the taskdata.promptJson (string, required)#
Original request parameters in JSON format, including prompt, video URL, callback URL, and watermark settingsdata.resultUrls (array)#
Generated video URLs. Only appears when completion is successful (code 200).Callback Receipt Examples#
Here are example codes for receiving callbacks in popular programming languages:Best Practices#
Callback URL Configuration Recommendations#
1.
Use HTTPS: Ensure your callback URL uses HTTPS protocol for secure data transmission
2.
Verify Origin: Verify the legitimacy of request sources in your callback processing
3.
Idempotent Processing: The same taskId may receive multiple callbacks, ensure processing logic is idempotent
4.
Fast 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
6.
Prompt Download: Generated videos may expire after a period of time, download and save immediately upon receiving a successful callback
Important Reminders#
Callback URL must be publicly accessible
Server must respond within 15 seconds, otherwise it will be considered a timeout
If three consecutive retries fail, the system will stop sending callbacks
Generated video URLs may expire - Download immediately upon receiving callback
Ensure the stability of callback processing logic to avoid failures due to exceptions
Need to handle both success and failure status codes for complete error handling
Large video files may take time to download - Implement appropriate timeout settings
Troubleshooting#
If you don't receive callback notifications, please check the following:Network Connection Issues
Confirm callback URL is accessible from the public internet
Check firewall settings to ensure inbound requests are not blocked
Verify domain name resolution is correct
Server Response Issues
Ensure server returns HTTP 200 status code within 15 seconds
Check server logs for error messages
Verify interface path and HTTP method are correct
Content Format Issues
Confirm received POST request body is in JSON format
Check if Content-Type is application/json
Verify JSON parsing is correct
Video Processing Issues
Confirm video URL is accessible
Check video download permissions and network connection
Verify video save paths and permissions
Handle video download timeouts and retry logic
Implement checksum validation for large video files
Task Failure Issues
Check if video modification parameters are reasonable
Verify input video format and quality
Confirm prompt length and format
Consider adjusting modification parameters and retrying
Review error messages in promptJson for debugging
Alternative Solutions#
If you cannot use the callback mechanism, you can also use polling:
Poll to Query Results
Use the Get Luma Modification Details endpoint to periodically query task status. For video generation tasks, we recommend querying every 30 seconds.