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

# 查询任务

> 轮询图像、视频或音频异步任务的状态。

无法在一次请求内完成的媒体生成会变成一个任务。这个接口返回某个任务的当前状态，
完成后一并返回结果。

<Info>
  通过 [`POST /v2/videos`](/zh/api-reference/video/create) 创建的视频有自己的任务信封和
  轮询路径 [`GET /v2/videos/{id}`](/zh/api-reference/video/get)。本接口用于 `/v1`
  媒体端点创建的任务。
</Info>

<ParamField path="task_id" type="string" required>
  任务 ID。由 PipeLLM 托管的任务以 `gen-` 开头；直接在上游创建的任务，也接受上游自己的
  任务 ID。
</ParamField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl https://api.pipellm.ai/v1/tasks/gen-1732891234-abc123xyz \
    -H "Authorization: Bearer $PIPELLM_API_KEY"
  ```

  ```python Python theme={"dark"}
  import os, time, requests

  headers = {"Authorization": f"Bearer {os.environ['PIPELLM_API_KEY']}"}

  while True:
      task = requests.get(
          f"https://api.pipellm.ai/v1/tasks/{task_id}", headers=headers
      ).json()

      if task["status"] in ("completed", "failed", "cancelled"):
          break
      time.sleep(3)

  print(task["status"], task.get("data"), task.get("error"))
  ```
</RequestExample>

<ResponseExample>
  ```json theme={"dark"}
  {
    "id": "gen-1732891234-abc123xyz",
    "status": "processing",
    "type": "video_generation",
    "model": "seedance-2-0-mini",
    "created_at": "2026-09-17T08:14:02Z"
  }
  ```
</ResponseExample>

<ResponseField name="id" type="string">
  任务 ID。查询和 [取消](/zh/api-reference/tasks/cancel) 都用它。
</ResponseField>

<ResponseField name="status" type="string">
  `pending`、`processing`、`completed`、`failed` 或 `cancelled` 之一。
</ResponseField>

<ResponseField name="type" type="string">
  `image_generation`、`image_edit`、`video_generation` 或 `audio_generation`。
</ResponseField>

<ResponseField name="model" type="string">
  产出结果的模型。
</ResponseField>

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

<ResponseField name="data" type="object">
  结果。`status` 为 `completed` 后出现，结构随任务 `type` 而定。
</ResponseField>

<ResponseField name="error" type="string">
  失败原因。`status` 为 `failed` 时出现。
</ResponseField>

## 轮询

任务的流转是 `pending` → `processing` → `completed` / `failed` / `cancelled` 之一。
只有这三个是终态，看到就停止轮询。

每隔几秒轮询一次即可，不要写成紧凑循环——轮询会计入你的
[速率限制](/zh/api-reference/rate-limits)，而且轮得再快上游也不会更早完成。

## 错误

错误信封与 [错误与排查](/zh/api-reference/errors) 一致。ID 不存在返回 `404`；属于其他
账户的任务对你不可见，同样返回 `404`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.