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

# Seedance 查询视频生成任务

> 查询视频生成任务的状态。

> 仅支持查询最近 7 天的任务记录，时间区间为 [T-7天, T)，其中 T 为请求发起时刻的 UTC 时间戳（精确到秒）。注意：视频 URL 有效期为 14 天，请及时下载或转存。



## OpenAPI

````yaml api-reference/zh-Hans/zmodelVideo/byteplus/seedance/seedance-tasks-query.json GET /byteplus/api/v3/contents/generations/tasks/{id}
openapi: 3.0.1
info:
  title: Seedance 查询视频生成任务
  version: 1.0.0
  description: >-
    查询视频生成任务的状态。


    > 仅支持查询最近 7 天的任务记录，时间区间为 [T-7天, T)，其中 T 为请求发起时刻的 UTC 时间戳（精确到秒）。注意：视频 URL
    有效期为 14 天，请及时下载或转存。


    ## 鉴权


    本接口支持 API Key 鉴权，详见鉴权认证方式。
servers:
  - url: https://api.powertokens.ai
    description: 火山方舟 API 服务地址
security: []
paths:
  /byteplus/api/v3/contents/generations/tasks/{id}:
    get:
      summary: request
      description: >-
        查询视频生成任务的状态。


        > 仅支持查询最近 7 天的任务记录，时间区间为 [T-7天, T)，其中 T 为请求发起时刻的 UTC 时间戳（精确到秒）。注意：视频 URL
        有效期为 14 天，请及时下载或转存。
      operationId: querySeedanceVideoTask
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
            default: application/json
          description: 请求内容类型。
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: |-
            您需要查询的视频生成任务的 ID 。

            > 说明：上面参数为Query String Parameters，在URL String中传入。
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryVideoTaskResponse'
              example:
                id: cgt-2026****-****
                model: doubao-seedance-2-0-260128
                status: succeeded
                content:
                  video_url: >-
                    https://ark-content-generation-cn-beijing.tos-cn-beijing.volces.com/xxx
                usage:
                  completion_tokens: 108900
                  total_tokens: 108900
                created_at: 1779348818
                updated_at: 1779348874
                seed: 78674
                resolution: 720p
                ratio: '16:9'
                duration: 5
                framespersecond: 24
                service_tier: default
                execution_expires_after: 172800
                generate_audio: true
                draft: false
                priority: 0
        '400':
          description: 请求参数不合法。
        '401':
          description: 鉴权失败。
        '429':
          description: 请求频率超限。
        '500':
          description: 服务端内部错误。
      security:
        - BearerAuth: []
components:
  schemas:
    QueryVideoTaskResponse:
      type: object
      properties:
        id:
          type: string
          description: 视频生成任务 ID。
        model:
          type: string
          description: 任务使用的模型名称和版本，`模型名称-版本`。
        status:
          type: string
          enum:
            - queued
            - running
            - cancelled
            - succeeded
            - failed
            - expired
          description: |-
            任务状态，以及相关的信息：

            * `queued`：排队中。
            * `running`：任务运行中。
            * `cancelled`：取消任务，取消状态24h自动删除（只支持排队中状态的任务被取消）。
            * `succeeded`： 任务成功。
            * `failed`：任务失败。
            * `expired`：任务超时。
        error:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ErrorObject'
          description: 错误提示信息，任务成功返回`null`，任务失败时返回错误数据
        created_at:
          type: integer
          description: 任务创建时间的 Unix 时间戳（秒）。
        updated_at:
          type: integer
          description: 任务当前状态更新时间的 Unix 时间戳（秒）。
        content:
          allOf:
            - $ref: '#/components/schemas/TaskContent'
          description: 视频生成任务的输出内容。
        seed:
          type: integer
          description: 本次请求使用的种子整数值。
        resolution:
          type: string
          description: 生成视频的分辨率。
        ratio:
          type: string
          description: 生成视频的宽高比。
        duration:
          type: integer
          description: |-
            生成视频的时长，单位：秒。

            说明：**duration 和 frames 参数只会返回一个**。创建视频生成任务时未指定 frames，会返回 duration。
        frames:
          type: integer
          description: |-
            生成视频的帧数。

            说明：**duration 和 frames 参数只会返回一个**。创建视频生成任务时指定了 frames，会返回 frames。
        framespersecond:
          type: integer
          description: 生成视频的帧率。
        generate_audio:
          type: boolean
          description: |-
            生成的视频是否包含与画面同步的声音。仅 seedance 2.0 & 2.0 fast、seedance 1.5 pro 会返回该参数。

            * `true`：模型输出的视频包含同步音频。
            * `false`：模型输出的视频为无声视频。
        tools:
          type: array
          description: 本次请求模型实际使用的工具。未使用工具时不返回。
          items:
            $ref: '#/components/schemas/TaskTool'
        safety_identifier:
          type: string
          description: 终端用户的唯一标识符。若 创建视频生成任务 时设置了该参数，接口会原样返回此信息。
        priority:
          type: integer
          description: 当前请求的执行优先级。
        draft:
          type: boolean
          description: |-
            生成的视频是否为 Draft 视频。仅 seedance 1.5 pro 会返回该参数。

            * `true`：表示当前输出为 Draft 视频。
            * `false`：表示当前输出为正常视频。
        draft_task_id:
          type: string
          description: Draft 视频任务 ID。基于 Draft 视频生成正式视频时，会返回该参数。
        service_tier:
          type: string
          description: 实际处理任务使用的服务等级。
        execution_expires_after:
          type: integer
          description: 任务超时阈值，单位：秒。
        usage:
          allOf:
            - $ref: '#/components/schemas/TaskUsage'
          description: 本次请求的 token 用量。
    ErrorObject:
      type: object
      properties:
        code:
          type: string
          description: 错误码。
        message:
          type: string
          description: 错误提示信息。
    TaskContent:
      type: object
      properties:
        video_url:
          type: string
          description: 生成视频的 URL，格式为 mp4。有效期为 14 天，请及时下载或转存。
        last_frame_url:
          type: string
          description: >-
            视频的尾帧图像 URL。有效期为 14 天，请及时下载或转存。说明：创建视频生成任务 时设置 `"return_last_frame":
            true` 时，会返回该参数。
    TaskTool:
      type: object
      properties:
        type:
          type: string
          enum:
            - web_search
          description: |-
            实际使用的工具类型

            * web_search：联网搜索工具。
    TaskUsage:
      type: object
      properties:
        completion_tokens:
          type: integer
          description: >-
            模型生成视频消耗的 token 数量，可作为计费对账依据。


            > seedance 2.0 系列模型存在最低 token 用量限制，如果实际 token 用量 ＜ 最低 token
            用量，本字段会返回最低 token 用量，平台按最低 token 用量计费。
        total_tokens:
          type: integer
          description: >-
            本次请求消耗的总 token 数量。视频生成模型不统计输入 token，输入 token 为 0，故 `total_tokens` =
            `completion_tokens`。
        tool_usage:
          allOf:
            - $ref: '#/components/schemas/ToolUsage'
          description: 使用工具的用量信息。
    ToolUsage:
      type: object
      properties:
        web_search:
          type: integer
          description: 实际调用联网搜索工具的次数，仅开启联网搜索时返回。
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: '在请求头中传入 `Authorization: Bearer <token>`。'

````