/api/v1/gpt-image-2/generateAsync Callbacks (GPT-2)
Use webhooks to receive GPT Image 2 results asynchronously. Recommended for GPT Image 2 — large and high-quality generations can take several minutes, and async mode avoids long-held synchronous connections that clients or proxies may time out. Ideal for high-quality 4K generations or non-blocking requests.
Overview
When you include a callbackUrl in your request, the API returns a 202 Accepted response immediately with a job ID. Once the image is generated, the result is sent as a POST request to your callback URL. You can also poll the job status using the returned statusUrl.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
callbackUrl | string | Yes | Your webhook URL to receive results |
Include callbackUrl alongside all other generation parameters (prompt, size, quality, etc.).
Example Request
curl -X POST https://eccoapi.com/api/v1/gpt-image-2/generate \
-H "Authorization: Bearer nk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A detailed architectural rendering of a modern glass building",
"size": "3840x2160",
"quality": "high",
"callbackUrl": "https://your-server.com/webhook"
}'Async Response (202 Accepted)
Returned immediately when a callbackUrl is provided. Use the jobId or statusUrl to track progress.
{
"code": 202,
"msg": "Job accepted",
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"statusUrl": "https://eccoapi.com/api/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"callbackUrl": "https://your-server.com/webhook"
}Callback Payload (Success)
Sent as a POST request to your callbackUrl when the image is ready.
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"code": 200,
"msg": "Success",
"data": {
"assetUrl": "https://<signed-url>",
"assetKey": "user/<userId>/gpt-image-2/....png",
"mimeType": "image/png",
"bytes": 4194304
},
"meta": {
"model": "gpt-image-2",
"cost": 0.32,
"remaining_credits": 9.68,
"settings": {
"size": "3840x2160",
"quality": "high",
"outputFormat": "png",
"moderation": "auto"
}
}
}Callback Payload (Failure)
Sent when image generation fails. Check the error code and message for details.
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "failed",
"code": 500,
"msg": "Generation failed",
"error": "The model was unable to generate an image for this prompt."
}