# 查询 AI 生成任务结果

- API 版本：1.10.0
- 最后更新：2026-09-29
- 服务地址：`https://api.ailingtu.com`
- 网页文档：[查询 AI 生成任务结果](/openapi/schedule-tasks)
- 完整接口约束：[JSON Schema](/openapi/operations/listAiTasksByScheduleId.json)
- 接口发现：[接口索引](/openapi/operations/index.json)

## GET /v1/ai/task/listByScheduleId

接口标识：`listAiTasksByScheduleId`

使用创建接口返回的 scheduleId 查询本次图片或视频生成任务。建议每 5 秒轮询，直到任务完成或明确失败。

鉴权：请求头 `x-api-key: <YOUR_API_KEY>`；密钥仅保存在服务端。

成功判断：HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `scheduleId` | query | string | 是 | 创建生成计划时返回的 scheduleId |

### 成功响应

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "taskId": "task_01k1example",
        "scheduleId": "schedule_01k1example",
        "type": "VIDEO_GENERATION",
        "status": "COMPLETED",
        "model": "gemini-omni-video",
        "params": {
          "prompt": "A clean 10-second product reveal video with a slow camera push-in",
          "model": "gemini-omni-video",
          "seconds": 10,
          "size": "720x1280"
        },
        "result": {
          "url": "https://static.ailingtu.com/ai-videos/result.mp4",
          "thumbnailUrl": "https://static.ailingtu.com/ai-images/cover.jpg"
        },
        "customResult": {
          "videoUrl": "https://static.ailingtu.com/ai-videos/result.mp4",
          "coverUrl": "https://static.ailingtu.com/ai-images/cover.jpg"
        },
        "createdAt": "2026-08-10T10:00:00Z"
      }
    ],
    "total": 1,
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 1
  },
  "message": "success"
}
```

### 响应字段

以下列出主要层级；完整结构、联合类型及校验规则以接口 JSON Schema 为准。必填指字段所在对象中的约束。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | integer | 是 | 固定值：0 |
| `message` | string | 否 | — |
| `data` | object | 是 | — |
| `data.list` | object[] | 是 | — |
| `data.list[].taskId` | string | 是 | — |
| `data.list[].scheduleId` | string | 否 | — |
| `data.list[].type` | string | 是 | 可选值：IMAGE_GENERATION、VIDEO_GENERATION |
| `data.list[].status` | string | 是 | 可选值：WAITING_SUBMIT、SUBMITTING、SUBMIT_FAILED、PENDING、PROCESSING、COMPLETED、FAILED、CANCELLED、EXPIRED |
| `data.list[].model` | string | 否 | — |
| `data.list[].params` | union | 否 | — |
| `data.list[].result` | object | 否 | — |
| `data.list[].result.url` | string | 否 | — |
| `data.list[].result.resultUrl` | string | 否 | — |
| `data.list[].result.videoUrl` | string | 否 | — |
| `data.list[].result.thumbnailUrl` | string | 否 | — |
| `data.list[].resultUrl` | string | 否 | — |
| `data.list[].customResult` | object | 否 | — |
| `data.list[].customResult.videoUrl` | string | 否 | — |
| `data.list[].customResult.coverUrl` | string | 否 | — |
| `data.list[].reason` | string \| null | 否 | — |
| `data.list[].createdAt` | string | 否 | — |
| `data.list[].finishTime` | string \| null | 否 | — |
| `data.total` | integer | 否 | — |
| `data.pageNumber` | integer | 否 | — |
| `data.pageSize` | integer | 否 | — |
| `data.totalPages` | integer | 否 | — |

### 接入说明与限制

- 等待状态包括 WAITING_SUBMIT、SUBMITTING、PENDING 和 PROCESSING；成功状态为 COMPLETED。
- 失败、取消或过期后再决定是否重试；网络错误或轮询进程退出不表示生成任务失败。
- 视频优先读取 customResult.videoUrl 或 result.url；图片通常读取 result.url 或 resultUrl。

### 错误处理

| HTTP | 说明 |
|---|---|
| 400 | 请求参数或请求体无效，请修正后重试。 |
| 401 | API 密钥缺失或无效，请检查 x-api-key。 |
| 403 | API 密钥没有此接口的调用权限。 |
| 429 | 请求过于频繁，请采用指数退避重试。 |
| 500 | 服务端发生错误；对于暂时性故障采用指数退避重试。 |

业务 code 非零时也应按失败处理。不要对参数、权限或授权错误盲目重试。创建发布或生成任务超时后先查询原任务，避免重复创建。

### 相关接口

- [创建 AI 图片或视频生成任务](/openapi/schedule-create) · [Markdown](/openapi/operations/createAiGenerationSchedule.md)