When the image generation task is completed, the system will send the result to your provided callback URL via POST request
When you submit an image generation or editing task to the Flux Kontext API, you can use the callBackUrl parameter to set a callback URL. The system will automatically push the 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:Image generation or editing task completed successfully
Image generation or editing task failed
Errors occurred during task processing
Callback Method#
Content Type: application/json
Timeout Setting: 15 seconds
callBackUrl in the following format:Content Policy Violation Callback
Generation Failure Callback
{
"code": 200,
"msg": "Image generated successfully.",
"data": {
"taskId": "task12345",
"info": {
"resultImageUrl": "https://example.com/result.jpg"
}
}
}
Status Code Description#
code (integer, required)#
Callback status code indicating task processing result:| Status Code | Description |
|---|
| 200 | Success - Image generation completed successfully |
| 400 | Failed - Your prompt was flagged by Website as violating content policies |
| 500 | Failed - Internal Error, Please try again later |
| 501 | Failed - Image generation 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.info.resultImageUrl (string)#
Generated image URL on our server. Only present on success.Callback Reception 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 Source: Verify the legitimacy of the request source 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 timeout
5.
Asynchronous Processing: Complex business logic should be processed asynchronously to avoid blocking callback response
Important Reminders#
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
Need to handle multiple error status codes (400, 500, 501) for complete error handling
Pay attention to content policy violations and adjust prompts accordingly
Troubleshooting#
If you do not receive callback notifications, please check the following:Network Connection Issues
Confirm that the callback URL is accessible from the public network
Check firewall settings to ensure inbound requests are not blocked
Verify that domain name resolution is correct
Server Response Issues
Ensure the server returns HTTP 200 status code within 15 seconds
Check server logs for error messages
Verify that the interface path and HTTP method are correct
Content Format Issues
Confirm that the received POST request body is in JSON format
Check that Content-Type is application/json
Verify that JSON parsing is correct
Image Processing Issues
Confirm that image URLs are accessible
Check image download permissions and network connections
Verify image save paths and permissions
Content Policy Issues
Review error messages for content policy violations
Adjust prompts that are flagged by content moderation
Ensure prompts comply with platform content guidelines
Check for sensitive or inappropriate content
Task Failure Issues
Check if generation parameters are reasonable
Verify input image format and quality
Confirm prompt length and format
Consider adjusting generation parameters and retry
Alternative Solution#
If you cannot use the callback mechanism, you can also use polling:
Poll Query Results
Use Get Task Details (GET /api/v1/jobs/recordInfo) to regularly query task status. We recommend querying every 30 seconds.