回调通知与轮询

对于支持回调的异步任务，可在创建任务时填写顶层 callBackUrl。这是你自己的服务接收通知的地址，需要使用公网可访问的 HTTPS；不能填写 localhost、内网地址或包含账号密码的地址。没有公网地址时，可以使用任务查询接口。

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

什么时候通知

任务成功或失败后，平台会向回调地址发送 POST 请求，内容类型为 application/json。保存创建响应中的平台任务 ID；回调中的 data.taskId 使用同一个平台任务 ID。结果字段随模型而变化，下面是图片任务的示例：

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

失败通知的示例：

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

resultJson 是 JSON 字符串；其他模型可能在 response 或其他结果字段中返回内容，具体以任务查询结果为准。示例中的地址和 ID 需要替换。

验证通知和处理重复消息

确认 data.taskId 是你此前创建并记录的任务，不要依据陌生任务 ID 修改业务状态。

使用你自己的平台 API 密钥查询该任务，以受认证的查询结果确认状态和内容；不要把 API 密钥放进回调 URL。

按任务 ID 和终态幂等处理。收到重复通知时，不要重复发货、计费或触发其他业务动作。

将通知安全持久化后尽快返回 HTTP 2xx；较慢的查询和后续业务处理放入后台队列。

部分部署可能提供签名请求头，但当前没有面向开发者的独立回调签名密钥管理。不要仅凭请求头或回调正文判定结果可信，仍需通过带令牌的任务查询确认。签名如果启用，只覆盖任务 ID 和时间戳，不覆盖整个正文。

超时、重试和轮询

接收服务应在 10 秒内响应；平台不跟随回调地址的重定向。非 2xx、超时或连接失败时，最多尝试投递 6 次；失败后的重试间隔依次为 15 秒、1 分钟、5 分钟、15 分钟和 1 小时。重复投递或网络中断都可能发生，建议保留查询兜底。

配置 BASE_URL、MAXROUTERAI_API_KEY 和创建响应中的 TASK_ID 后再运行。任务查询应使用创建该任务的账号及有权限的令牌。部分同步操作直接返回结果，不会产生异步回调。

回调通知与轮询

什么时候通知#

验证通知和处理重复消息#

超时、重试和轮询#

什么时候通知

验证通知和处理重复消息

超时、重试和轮询