> ## 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.

# 查询视频任务（方舟兼容）

> 轮询通过火山方舟兼容端点创建的异步视频生成任务状态。

使用创建接口返回的任务 `id` 轮询本接口，直到任务到达终态。生产环境建议在创建请求中设置 `callback_url`，避免高频轮询。任务记录的保留窗口与 APIPod 原生任务一致；任务成功后请及时下载或转存视频 URL。

## 任务状态

| `status`    | 含义                                 | 建议动作                               |
| ----------- | ---------------------------------- | ---------------------------------- |
| `queued`    | 任务排队中。                             | 等待后继续轮询。                           |
| `running`   | 任务执行中。                             | 等待后继续轮询。                           |
| `succeeded` | 任务成功，视频 URL 在 `content.video_url`。 | 下载并保存产物。                           |
| `failed`    | 任务失败，详情见 `error`。                  | 查看 `error.code` 与 `error.message`。 |
| `cancelled` | 任务已取消。                             | 停止轮询。                              |

## 用量与费用

`status` 为 `succeeded` 时，响应携带 `usage` 对象，包含本任务的最终扣费金额。`cost` 为完成后的结算金额（USD），与控制台展示一致；它是 APIPod 对方舟契约的扩展字段，始终返回。token 字段仅在上游回传用量时出现。

任务不存在与任务属于其他账号统一返回 404，两种情况不做区分。


## OpenAPI

````yaml api-reference/openapi/ark-query-video-task.zh.yaml GET /api/v3/contents/generations/tasks/{id}
openapi: 3.1.0
info:
  title: 查询视频生成任务 API（方舟兼容）
  version: 1.0.0
  description: 火山方舟兼容的异步视频生成任务查询端点。使用创建接口返回的任务 ID 轮询本接口，直到任务到达终态。
servers:
  - url: https://api.apipod.ai
    description: 生产环境
security: []
paths:
  /api/v3/contents/generations/tasks/{id}:
    get:
      tags:
        - 视频任务
      summary: 查询视频生成任务
      operationId: get-ark-query-video-task
      parameters:
        - name: id
          in: path
          required: true
          description: 创建接口返回的任务 ID。
          schema:
            type: string
          example: 0f4c9f6e-1111-4c1d-8c2f-2b7b9a1c4d55
      responses:
        '200':
          description: 任务状态快照
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: 任务 ID。
                  model:
                    type: string
                    description: 本任务使用的公开模型系列名。
                  status:
                    type: string
                    enum:
                      - queued
                      - running
                      - succeeded
                      - failed
                      - cancelled
                    description: 方舟语义的任务状态。
                  content:
                    type: object
                    properties:
                      video_url:
                        type: string
                        description: 生成视频的 URL，请及时下载或转存；仅在任务成功后出现。
                    description: 输出内容，仅在任务成功后出现。
                  created_at:
                    type: integer
                    description: 任务创建时间（Unix 秒级时间戳）。
                  updated_at:
                    type: integer
                    description: 任务最近一次状态更新时间（Unix 秒级时间戳）。
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: 方舟风格错误码。
                      message:
                        type: string
                        description: 面向客户端的安全错误信息。
                    description: 仅在任务失败时出现。
                  usage:
                    type: object
                    properties:
                      completion_tokens:
                        type: integer
                        description: 上游回传的生成 token 数，可用时返回。
                      total_tokens:
                        type: integer
                        description: 上游回传的总 token 数，可用时返回。
                      cost:
                        type: number
                        description: 本任务最终扣费金额（USD），与控制台一致。APIPod 扩展字段。
                    required:
                      - cost
                    description: 终态用量快照，仅在任务成功后出现。
                required:
                  - id
                  - model
                  - status
              example:
                id: 0f4c9f6e-1111-4c1d-8c2f-2b7b9a1c4d55
                model: seedance-2.5
                status: succeeded
                content:
                  video_url: https://cdn.example.com/generated.mp4
                created_at: 1786358400
                updated_at: 1786358523
                usage:
                  completion_tokens: 123
                  total_tokens: 123
                  cost: 0.053
        '401':
          description: 鉴权失败。
        '404':
          description: 任务不存在，或任务属于其他账号。
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIPod API key
      description: 在 Authorization 头中以 Bearer 方式携带 APIPod API Key。

````