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

# 获取任务状态

> 查询视频任务执行状态并获取生成的视频文件

# 获取任务状态

查询视频生成任务的执行状态，并在完成后获取生成的视频。

## 接口

```http theme={"dark"}
GET https://api.poyo.ai/api/generate/status/{task_id}
```

## 认证

所有请求都需要 Bearer token 认证：

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## 参数

### 路径参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `task_id` | string | 是 | 提交接口返回的唯一任务标识 |

## 响应

### 成功响应（200）

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165211-xyz789",
    "status": "finished",
    "credits_amount": 20,
    "files": [
      {
        "file_url": "https://storage.poyo.ai/generated/video-xyz789.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2025-11-12T10:30:00",
    "progress": 100,
    "error_message": null
  }
}
```

### 响应字段

| 字段 | 类型 | 说明 |
| - | - | - |
| `code` | integer | HTTP 状态码（成功为 200） |
| `data.task_id` | string | 唯一任务标识 |
| `data.status` | string | 任务状态：`not_started`、`running`、`finished`、`failed` |
| `data.credits_amount` | number | 该任务扣除的积分 |
| `data.files` | array | 状态为 `finished` 时生成的视频 |
| `data.files[].file_url` | string | 生成文件的直链 URL |
| `data.files[].file_type` | string | 生成文件的类型，通常为 `video` |
| `data.created_time` | string | 任务创建时间，ISO 8601 格式 |
| `data.progress` | integer | 完成百分比（0-100） |
| `data.error_message` | string | 状态为 `failed` 时的错误说明 |

### 状态值

| 状态 | 说明 |
| - | - |
| `not_started` | 任务已排队，等待处理 |
| `running` | 任务正在生成中 |
| `finished` | 任务成功完成，结果在 `files` 中 |
| `failed` | 任务失败，错误详情在 `error_message` 中 |

### 失败任务

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165211-xyz789",
    "status": "failed",
    "credits_amount": 0,
    "files": [],
    "created_time": "2025-11-12T10:30:00",
    "progress": 0,
    "error_message": "The prompt violates our content policy"
  }
}
```

## 代码示例

```bash theme={"dark"}
curl -X GET https://api.poyo.ai/api/generate/status/task-unified-1757165211-xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## 重要说明

> [!TIP]
>
> **轮询间隔**：每 2-5 秒查询一次状态。视频生成通常需要 90-300 秒。

> [!WARNING]
>
> **内容有效期**：生成的视频在创建后 **3 天**内可访问。请及时下载并保存内容。

> [!TIP]
>
> **Webhook**：除了轮询，你还可以在提交任务时提供 `callback_url` 来自动接收通知。参见[视频 Webhook 回调](https://docs.poyo.ai/zh/api-manual/task-management/video-webhooks.md)。

更多语言的代码示例、带退避的轮询以及 HTTP 错误码，请参见[统一任务状态](https://docs.poyo.ai/zh/api-manual/task-management/status.md)页面。


## OpenAPI

````yaml zh/api-manual/task-management/video-status.json GET /api/generate/status/{task_id}
openapi: 3.1.0
info:
  title: PoYo AI - 视频任务状态 API
  description: 查询视频任务执行状态并获取生成的视频文件
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
security:
  - BearerAuth: []
paths:
  /api/generate/status/{task_id}:
    get:
      tags:
        - Video Task Management
      summary: 查询视频任务状态
      operationId: queryVideoTaskStatus
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 提交接口返回的唯一任务标识
      responses:
        '200':
          description: 任务状态
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              examples:
                finished:
                  summary: 已完成的视频任务
                  value:
                    code: 200
                    data:
                      task_id: task-unified-1757165211-xyz789
                      status: finished
                      credits_amount: 20
                      files:
                        - file_url: https://storage.poyo.ai/generated/video-xyz789.mp4
                          file_type: video
                      created_time: '2025-11-12T10:30:00'
                      progress: 100
components:
  schemas:
    StatusResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
        data:
          $ref: '#/components/schemas/TaskStatus'
      example:
        code: 200
        data:
          task_id: task-unified-1757165211-xyz789
          status: finished
          credits_amount: 20
          files:
            - file_url: https://storage.poyo.ai/generated/video-xyz789.mp4
              file_type: video
          created_time: '2025-11-12T10:30:00'
          progress: 100
    TaskStatus:
      type: object
      properties:
        task_id:
          type: string
        status:
          type: string
          enum:
            - not_started
            - running
            - finished
            - failed
          example: finished
          description: |-
            任务状态。

            - `not_started`：排队中，等待处理
            - `running`：生成中
            - `finished`：已完成，结果在 `files` 或 `output` 中
            - `failed`：失败，详情见 `error_message`
        credits_amount:
          type: number
          description: 任务消耗的积分
          example: 20
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileItem'
        created_time:
          type: string
          format: date-time
        progress:
          type: number
          example: 100
        error_message:
          type:
            - string
            - 'null'
      example:
        task_id: task-unified-1757165211-xyz789
        status: finished
        credits_amount: 20
        files:
          - file_url: https://storage.poyo.ai/generated/video-xyz789.mp4
            file_type: video
        created_time: '2025-11-12T10:30:00'
        progress: 100
    FileItem:
      type: object
      required:
        - file_url
        - file_type
      properties:
        label:
          type: string
          description: 模型提供时返回的可选文件标签
        file_url:
          type: string
          format: uri
          example: https://storage.poyo.ai/generated/video-xyz789.mp4
        file_type:
          type: string
          enum:
            - image
            - video
            - audio
            - 3d
            - other
          example: video
        format:
          type: string
          description: 模型提供时返回的可选文件格式
        content_type:
          type: string
          description: 模型提供时返回的可选 MIME 类型
        file_name:
          type: string
          description: 模型提供时返回的可选文件名
        file_size:
          type: integer
          description: 模型提供时返回的可选文件大小（字节）
      example:
        file_url: https://storage.poyo.ai/generated/video-xyz789.mp4
        file_type: video
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证。


        创建 API Key：登录 PoYo，进入 **仪表盘 → API
        密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建
        Key。


        在请求头中添加：


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

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