# List AI generation tasks

- API version: 1.11.0
- Last updated: 2026-11-16
- Server: `https://api.ailingtu.com`
- Web document: [List AI generation tasks](/en/openapi/schedule-tasks)
- Full schema: [JSON Schema](/en/openapi/operations/listAiTasksByScheduleId.json)
- Discovery: [Operation index](/en/openapi/operations/index.json)

## GET /v1/ai/task/listByScheduleId

Operation ID: `listAiTasksByScheduleId`

List image or video generation tasks using the scheduleId returned at creation. Poll about every five seconds until tasks complete or explicitly fail.

Authentication: Request header `x-api-key: <YOUR_API_KEY>`; keep the key on the server and never expose it in client code, logs or shared files.

Success criteria: HTTP 2xx with code=0; for asynchronous tasks, also query the final status.

### Request parameters

| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| `scheduleId` | query | string | Yes | scheduleId returned when the generation schedule was created |

### Success response

```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"
}
```

### Response fields

Main levels are listed below. The endpoint JSON Schema is authoritative for the full structure, unions and validation rules; Required refers to the containing object.

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | integer | Yes | Fixed value: 0 |
| `message` | string | No | — |
| `data` | object | Yes | — |
| `data.list` | object[] | Yes | — |
| `data.list[].taskId` | string | Yes | — |
| `data.list[].scheduleId` | string | No | — |
| `data.list[].type` | string | Yes | Allowed values: IMAGE_GENERATION, VIDEO_GENERATION |
| `data.list[].status` | string | Yes | Allowed values: WAITING_SUBMIT, SUBMITTING, SUBMIT_FAILED, PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED, EXPIRED |
| `data.list[].model` | string | No | — |
| `data.list[].params` | union | No | — |
| `data.list[].result` | object | No | — |
| `data.list[].result.url` | string | No | — |
| `data.list[].result.resultUrl` | string | No | — |
| `data.list[].result.videoUrl` | string | No | — |
| `data.list[].result.thumbnailUrl` | string | No | — |
| `data.list[].resultUrl` | string | No | — |
| `data.list[].customResult` | object | No | — |
| `data.list[].customResult.videoUrl` | string | No | — |
| `data.list[].customResult.coverUrl` | string | No | — |
| `data.list[].reason` | string \| null | No | — |
| `data.list[].createdAt` | string | No | — |
| `data.list[].finishTime` | string \| null | No | — |
| `data.total` | integer | No | — |
| `data.pageNumber` | integer | No | — |
| `data.pageSize` | integer | No | — |
| `data.totalPages` | integer | No | — |

### Integration notes and limits

- Waiting states include WAITING_SUBMIT, SUBMITTING, PENDING, and PROCESSING. COMPLETED is successful.
- Retry only after an explicit failure, cancellation, or expiration. A network or polling-process error does not mean generation failed.
- For videos, prefer customResult.videoUrl or result.url. Images usually use result.url or resultUrl.

### Error handling

| HTTP | Description |
|---|---|
| 400 | The request parameters or body are invalid. Fix them and retry. |
| 401 | The API key is missing or invalid. Check x-api-key. |
| 403 | The API key has no permission to call this endpoint. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | The server failed. Retry transient failures with exponential backoff. |

Treat any non-zero business code as a failure. Do not blindly retry parameter, permission or authorization errors. If creating a publishing or generation task times out, query the existing task first instead of creating another one.

### Related endpoints

- [Create an AI image or video schedule](/en/openapi/schedule-create) · [Markdown](/en/openapi/operations/createAiGenerationSchedule.md)
