Callbacks and polling

For asynchronous tasks that support callbacks, set the top-level callBackUrl to your application's publicly reachable HTTPS endpoint. Do not use localhost, a private-network address, or a URL containing credentials. Without a public endpoint, query the task instead.

{
  "model": "gpt-image-2-5-flare-text-to-image",
  "input": {"prompt": "An orange cat", "resolution": "1K", "aspect_ratio": "1:1"},
  "callBackUrl": "https://your-app.example.com/callback"
}

When notifications are sent

The platform sends an application/json POST when the task succeeds or fails. Store the platform task ID from the creation response; the callback uses the same ID in data.taskId. Result fields vary by model. This example shows an image task:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_example",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://example.com/result.png\"]}"
  }
}

Example failure notification:

{
  "code": 501,
  "msg": "Task failed",
  "data": {"taskId": "task_example", "state": "fail", "failMsg": "Task failed"}
}

resultJson is a JSON string. Other models may return output in response or other fields; use the task query result for the model's actual shape. Replace the example URLs and IDs.

Verify notifications and handle duplicates

Confirm that data.taskId belongs to a task your application created and recorded. Do not update business state for an unknown task.

Query the task with your platform API key to confirm its status and result. Do not put the API key in the callback URL.

Process the task ID and terminal state idempotently so repeated messages do not trigger duplicate fulfillment, charges, or other actions.

Persist the notification securely and promptly return HTTP 2xx. Perform slower queries and business work in a background queue.

Some deployments may send signature headers, but the platform does not currently provide separate callback-signing key management for developers. Do not trust headers or the callback body alone; confirm the result through the authenticated task query. If enabled, a signature covers only the task ID and timestamp, not the entire body.

Timeouts, retries and polling

The receiver should respond within 10 seconds. The platform does not follow callback redirects. A non-2xx response, timeout, or connection failure is attempted at most six times, with delays of 15 seconds, 1 minute, 5 minutes, 15 minutes, and 1 hour after successive failures. Duplicates or network failures can occur, so retain polling as a fallback.

Set BASE_URL, MAXROUTERAI_API_KEY, and the creation response's TASK_ID before running the example. Use an account and token authorized to access the task. Some synchronous operations return a result directly and do not issue an asynchronous callback.

Callbacks and polling

When notifications are sent#

Verify notifications and handle duplicates#

Timeouts, retries and polling#

When notifications are sent

Verify notifications and handle duplicates

Timeouts, retries and polling