> ## 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.

# 查询任务

> 查询任务状态和结果

根据 `taskId` 查询任务的当前状态和生成结果。

<ParamField path="taskId" type="string" required>
  提交任务时返回的任务 ID。
</ParamField>

### 响应字段

<ResponseField name="code" type="integer">
  状态码，`0` 表示成功。
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="taskId" type="string">
      任务 ID。
    </ResponseField>

    <ResponseField name="status" type="string">
      任务状态：`PENDING`、`PROCESSING`、`SUBMITTED`、`SUCCESS`、`FAILURE`、`TIMEOUT`、`CANCELLED`。
    </ResponseField>

    <ResponseField name="input" type="object">
      提交时的完整输入参数（包含 model）。
    </ResponseField>

    <ResponseField name="result" type="object">
      任务结果，仅在 `SUCCESS` 时有值，其他终态为 `null`。

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          结果类型：`image` 或 `video`。
        </ResponseField>

        <ResponseField name="urls" type="string[]">
          生成资源的 URL 列表。图片可能多张，视频通常 1 个。

          <Warning>文件链接有效期为 **7 天**，请及时下载保存。</Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="failure_reason" type="string | null">
      机器可读的失败分类，始终存在；无特定可操作原因时为 `null`。

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

    <ResponseField name="created_at" type="string">
      任务创建时间（ISO 8601）。
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      任务最后更新时间（ISO 8601）。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.maxapi.io/api/v1/task/9db7d1ed-d1e5-4d11-9f3a-61f653b905ad \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 SUCCESS theme={null}
  {
    "code": 0,
    "msg": "ok",
    "data": {
      "taskId": "9db7d1ed-d1e5-4d11-9f3a-61f653b905ad",
      "status": "SUCCESS",
      "input": {
        "model": "nano-banana",
        "prompt": "赛博朋克风格的东京街景",
        "ratio": "16:9",
        "resolution": "2k"
      },
      "result": {
        "type": "image",
        "urls": [
          "https://example.com/output/image1.png",
          "https://example.com/output/image2.png"
        ]
      },
      "created_at": "2026-02-10T21:54:46.686768Z",
      "updated_at": "2026-02-10T21:55:04.039815Z"
    }
  }
  ```

  ```json 200 PROCESSING theme={null}
  {
    "code": 0,
    "msg": "ok",
    "data": {
      "taskId": "9db7d1ed-d1e5-4d11-9f3a-61f653b905ad",
      "status": "PROCESSING",
      "input": {
        "model": "nano-banana",
        "prompt": "赛博朋克风格的东京街景"
      },
      "result": null,
      "failure_reason": null,
      "created_at": "2026-02-10T21:54:46.686768Z",
      "updated_at": "2026-02-10T21:54:48.000000Z"
    }
  }
  ```

  ```json 200 FAILURE theme={null}
  {
    "code": 0,
    "msg": "ok",
    "data": {
      "taskId": "9db7d1ed-d1e5-4d11-9f3a-61f653b905ad",
      "status": "FAILURE",
      "input": {
        "model": "veo3",
        "prompt": "..."
      },
      "result": null,
      "failure_reason": "INVALID_PARAMETERS",
      "created_at": "2026-02-10T21:54:46.686768Z",
      "updated_at": "2026-02-10T21:54:55.000000Z"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "code": 404,
    "msg": "task not found"
  }
  ```
</ResponseExample>