Task Completion Callback (Webhook)

When submitting async generation tasks such as video / image / audio, you can include a callback URL. Once the task finishes (succeeds or fails), we'll actively POST the result to your URL, so you don't have to keep polling. For video and image generation tasks, you can also use language to choose the language of failure messages.

Quick start

When submitting a task, add webhook at the top level of the request body. To translate failure messages, also add language:

curl -X POST https://your-access-domain/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red apple on a table",
    "size": "1024x1024",
    "webhook": "https://your-server.com",
    "language": "en"
  }'

After the task is done, we'll send a POST request to your URL + /callback.

Choose the error message language

language is an optional string parameter that only affects error.message in failure callbacks. Task IDs, status, progress, cost, and result URLs do not change with the language. If omitted, the original error message from the upstream provider or platform is returned.

• Values are case-insensitive, and surrounding whitespace is trimmed. For example, "EN" and " en " are both treated as en.
• Use the two-letter codes in the table. Regional tags such as zh-CN, en-US, and pt-BR are not recognized.
• Unsupported values do not cause task submission to fail; the callback keeps the original error message.
• If the original message is already in the target language, it is returned unchanged instead of being translated again.
• If translation fails, the original message is returned without delaying or dropping the callback.

URL rules

The webhook you provide is the base URL, and we automatically append /callback:

So your server needs an endpoint that accepts POST .../callback.

What you'll receive

The pushed payload is exactly the same as what the "Get Task Status" endpoint returns — you can process it with the same parsing logic.

Code example

{
  "id": "task_01KV7FXR8BEYS1BWHJCT3JMCJ5",
  "status": "completed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589058,
  "actual_time": 29,
  "cost": 0.006,
  "credits_cost": 0.06,
  "result": {
    "images": [{ "url": ["https://.../result.png"], "expires_at": 1781675458 }]
  }
}

{
  "id": "task_xxx",
  "status": "failed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589050,
  "error": {
    "message": "The input image cannot be accessed. Make sure the URL is publicly accessible.",
    "type": "task_failed",
    "param": "",
    "code": "task_failed"
  }
}

Retries and deduplication (important)

• Retries: If your server doesn't return 2xx within about 10 seconds, or returns 5xx, we'll retry automatically, up to 3 times, at intervals of roughly 10s, 30s, and 60s. If all 3 fail we give up (within about 2 minutes).
• No retry: If your endpoint returns 4xx (treated as a bad URL / request), we give up immediately without retrying.
• Deduplication: Normally a task is pushed only once. But in extreme cases (e.g. a restart on our side after sending but before confirmation) you may receive duplicate pushes. Be sure to deduplicate idempotently by id (task_id) to avoid double-processing.

Recommendations for your receiving endpoint:

1. Return 2xx as soon as possible

Accept and enqueue first, then process asynchronously — don't make us wait for your processing to finish.

2. Deduplicate by id

Use id (task_id) as the idempotency key to avoid double-processing.

3. Configure and verify the signature

In production, verify the origin of callback requests and reject forged ones.

Requirements for the callback URL

For security, the callback URL must meet the following:

URLs that don't meet these requirements are dropped (no push, no retry).

FAQ

Minimal receiver example

from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        n = int(self.headers.get("Content-Length") or 0)
        body = self.rfile.read(n)
        data = json.loads(body)
        print("Received task callback:", data["id"], data["status"])
        # TODO: deduplicate by id, verify the signature, then process
        self.send_response(200); self.end_headers()
        self.wfile.write(b'{"ok":true}')

HTTPServer(("0.0.0.0", 443), H).serve_forever()

Return 200 as soon as possible, and run your processing logic asynchronously in the background.

This documentation is built and hosted on Mintlify, a developer documentation platform.