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

# 查询视频任务

> 使用 task_id 查询异步视频生成任务的状态、进度、结果和错误信息。

创建视频任务后，使用响应中的 `task_id` 调用本接口。任务完成前可以按合理间隔轮询；生产环境优先在创建请求中设置 `callback_url`。

## 任务状态

| `status`     | 含义                       | 建议动作         |
| ------------ | ------------------------ | ------------ |
| `pending`    | 任务正在排队。                  | 继续等待或轮询。     |
| `processing` | 提供商正在生成。                 | 继续等待或轮询。     |
| `completed`  | 任务完成，结果位于 `data.result`。 | 下载并持久化结果。    |
| `failed`     | 任务失败。                    | 检查错误字段和请求日志。 |
| `cancelled`  | 任务已取消。                   | 停止轮询。        |


## OpenAPI

````yaml api-reference/openapi/query-video-task.zh.yaml GET /v1/videos/status/{task_id}
openapi: 3.1.0
info:
  title: 查询视频任务 API
  version: 1.0.0
servers:
  - url: https://api.apipod.ai
    description: 生产环境
security: []
paths:
  /v1/videos/status/{task_id}:
    get:
      tags:
        - 视频任务
      summary: 查询生成任务
      operationId: get-query-video-task
      parameters:
        - name: task_id
          in: path
          required: true
          description: 创建接口返回的 APIPod 异步任务 ID。
          schema:
            type: string
          example: vid_task_01JEXAMPLE
      responses:
        '200':
          description: 任务状态
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: HTTP 状态码。
                    const: 200
                  message:
                    type: string
                    description: 响应消息。
                    const: success
                  data:
                    type: object
                    properties:
                      task_id:
                        type: string
                        description: 用于查询任务状态的 APIPod 任务 ID。
                      status:
                        type: string
                        description: 任务当前状态。
                        enum:
                          - pending
                          - processing
                          - completed
                          - failed
                          - cancelled
                      progress:
                        type: integer
                        description: 任务完成进度（提供商返回时可用）。 最小值：0。 最大值：100。
                      result:
                        type: array
                        items:
                          type: string
                        description: 任务完成后返回的生成结果 URL 列表。
                      completed_at:
                        type: integer
                        description: 任务完成时间，Unix 秒级时间戳。
                      error:
                        type: string
                        description: 可安全返回给客户端的异步错误信息。
                    required:
                      - task_id
                      - status
                    description: 响应数据。
                required:
                  - code
                  - message
                  - data
              example:
                code: 200
                message: success
                data:
                  task_id: vid_task_01JEXAMPLE
                  status: completed
                  progress: 100
                  result:
                    - https://cdn.example.com/generated.mp4
                  completed_at: 1786358400
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIPod API key
      description: 在 Authorization 请求头中使用 Bearer APIPod_API_KEY。

````