/api/v1/nanobanana/generate-2), 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 eliminates the need for you to poll the API to query task status. The system will actively push task completion results to your server.
Callback Timing
The system will send callback notifications in the following situations:- NanoBanana Generate-2 image generation task completed successfully
- NanoBanana Generate-2 image 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 task completion, the system will send a POST request to yourcallBackUrl. The actual response structure in production looks like the following:
Field and Status Description
Top-level
In the current implementation it is typically 200 for normal callbacks.
Whether the generation task is successful should be determined by
code field indicating whether the callback request itself is successful.In the current implementation it is typically 200 for normal callbacks.
Whether the generation task is successful should be determined by
data.successFlag and data.errorCode.Status message, usually
"success". For detailed failure reasons, refer to data.errorMessage.Task ID, consistent with the
taskId returned when you submitted the task.Generation status flag, with the same meaning as the Get Task Details endpoint:
Error code when
successFlag ≠ 1, indicating the failure reason, for example:422: The input or output was flagged as sensitive content (see the sensitive content failure example above)
Error message string, usually containing more detailed description for the failure.
Generated image URL on our server. Only present when
successFlag = 1 and generation succeeds.JSON string snapshot of the request parameters for this task. Useful for debugging and auditing.
Internal model/config identifier, for example
"nano-banana-2_1k".Task creation time.
Task completion time.
Callback Reception Examples
Here are example codes for receiving NanoBanana Generate-2 callbacks in popular programming languages:- Node.js
- Python
- PHP
Best Practices
Troubleshooting
If you haven’t received callback notifications, please check the following:Network Connection Issues
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
Server Response Issues
- Ensure server returns HTTP 200 status code within 15 seconds
- Check server logs for error information
- Verify interface path and HTTP method are correct
Content Format Issues
Content Format Issues
- Confirm received POST request body is in JSON format
- Check if Content-Type is application/json
- Verify JSON parsing is correct
Image Processing Issues
Image Processing Issues
- Confirm image URL is accessible
- Check image download permissions and network connection
- Verify image save path and permissions
- Implement reasonable image download and storage logic
Content Policy Issues
Content Policy Issues
- Review content policy violation prompts in error messages
- Adjust flagged prompt content
- Ensure prompts comply with platform content guidelines
- Check for sensitive or inappropriate content
Task Failure Issues
Task Failure Issues
- Check if generation parameters are reasonable
- Verify input image format and quality (for auto aspect ratio)
- 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:Polling Query Results
Use the get task details interface to periodically query task status, recommended every 30 seconds.