> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 回调通知

> 任务完成后的回调通知

当任务到达终态（`SUCCESS` / `FAILURE` / `TIMEOUT` / `CANCELLED`）时，如果提交时指定了 `callBackUrl`，系统会向该地址发送 POST 请求。

## 回调格式

```
POST <callBackUrl>
Content-Type: application/json
```

回调 `data` 字段与查询接口响应格式完全一致：

```json 成功 theme={null}
{
  "code": 0,
  "msg": "ok",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "SUCCESS",
    "input": {
      "model": "veo3",
      "prompt": "a cat walking in the garden",
      "ratio": "16:9",
      "resolution": "1080p",
      "duration": 10
    },
    "result": {
      "type": "video",
      "urls": ["https://media.example.com/videos/2026/02/26/a1b2c3d4.mp4"]
    },
    "failure_reason": null,
    "created_at": "2026-02-26T07:42:43Z",
    "updated_at": "2026-02-26T10:12:55Z"
  }
}
```

```json 失败（内容审核） theme={null}
{
  "code": 0,
  "msg": "ok",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "FAILURE",
    "input": {
      "model": "veo3",
      "prompt": "...",
      "ratio": "16:9",
      "resolution": "1080p",
      "duration": 10
    },
    "result": null,
    "failure_reason": "CONTENT_MODERATION",
    "created_at": "2026-02-26T07:42:43Z",
    "updated_at": "2026-02-26T07:42:55Z"
  }
}
```

## result 字段结构

**SUCCESS 时：**

| 字段     | 类型        | 说明                                      |
| ------ | --------- | --------------------------------------- |
| `type` | string    | 结果类型：`image`（图片）或 `video`（视频）           |
| `urls` | string\[] | 资源 URL 列表。图片可能多张，视频通常 1 个。**链接有效期 7 天** |

**FAILURE / TIMEOUT / CANCELLED 时：**

`result` 为 `null`。

## failure\_reason

始终存在于响应中，无特定可操作原因时为 `null`。

**枚举值：**

| 值                     | 含义                                            | 建议处理方式                |
| --------------------- | --------------------------------------------- | --------------------- |
| `CONTENT_MODERATION`  | Prompt 或图片因包含真人人脸、受版权保护的人物或公众人物，或 NSFW 内容而被拒绝 | 告知用户内容违规；**不要重试**     |
| `INVALID_PARAMETERS`  | 传入参数不正确                                       | 修正请求参数后再提交；**不要直接重试** |
| `INSUFFICIENT_POINTS` | 账户积分不足                                        | 引导用户充值；**不要重试**       |
| `null`                | 无特定可操作原因（瞬态错误、超时等）                            | 视情况可重试                |

## 注意事项

<Warning>
  * Webhook 超时时间为 5 秒，异步发送不阻塞主流程
  * 发送失败仅记录日志，**不会重试**
  * `callBackUrl` 不支持 localhost / 127.0.0.1 等内网地址（SSRF 防护）
  * 外层 `code` 始终为 `0`，需要通过 `data.status` 判断成功或失败
</Warning>