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

# 查询视频生成任务列表

> 通过传入筛选参数，查询符合条件的视频生成任务。仅支持查询最近 7 天的任务记录，时间区间为 [T-7天, T)，其中 T 为请求发起时刻的 UTC 时间戳（精确到秒）。

> 说明：下面参数为Query String Parameters，在URL String中传入。



## OpenAPI

````yaml api-reference/zh-Hans/zmodelVideo/byteplus/seedance/list-video-generation-tasks.json GET /byteplus/api/v3/contents/generations/tasks
openapi: 3.0.1
info:
  title: 查询视频生成任务列表
  version: 1.0.0
  description: >-
    通过传入筛选参数，查询符合条件的视频生成任务。仅支持查询最近 7 天的任务记录，时间区间为 [T-7天, T)，其中 T 为请求发起时刻的 UTC
    时间戳（精确到秒）。
  license:
    name: Project License
    url: https://github.com/QuantumNous/new-api/blob/main/LICENSE
servers:
  - url: https://api.powertokens.ai
    description: Baze API 服务地址
security: []
tags:
  - name: Seedance Video
    description: Seedance 系列视频生成能力
paths:
  /byteplus/api/v3/contents/generations/tasks:
    get:
      tags:
        - Seedance Video
      summary: 查询视频生成任务列表
      description: >-
        通过传入筛选参数，查询符合条件的视频生成任务。仅支持查询最近 7 天的任务记录，时间区间为 [T-7天, T)，其中 T 为请求发起时刻的
        UTC 时间戳（精确到秒）。


        > 说明：下面参数为Query String Parameters，在URL String中传入。
      operationId: byteplusListVideoGenerationTasks
      parameters:
        - name: page_num
          in: query
          required: false
          description: 返回结果的页码。
          schema:
            type: integer
            nullable: true
            default: 1
            minimum: 1
            maximum: 500
        - name: page_size
          in: query
          required: false
          description: 每页显示的结果数量。
          schema:
            type: integer
            nullable: true
            default: 20
            minimum: 1
            maximum: 500
        - name: filter.status
          in: query
          required: false
          description: |-
            过滤参数，查询某个任务状态。

            - queued：排队中的任务。
            - running：运行中任务。
            - cancelled：取消的任务。
            - succeeded：任务的成功。
            - failed：失败的任务。
          schema:
            type: string
            nullable: true
            enum:
              - queued
              - running
              - cancelled
              - succeeded
              - failed
        - name: filter.task_ids
          in: query
          required: false
          description: >-
            视频生成任务 ID，精确搜索，支持同时搜索多个任务
            ID。需通过重复参数名的方式传递，例如：`filter.task_ids=id1&filter.task_ids=id2`。
          style: form
          explode: true
          schema:
            type: array
            nullable: true
            items:
              type: string
        - name: filter.model
          in: query
          required: false
          description: 与返回参数不同，该字段为任务使用的推理接入点 ID，精确搜索。
          schema:
            type: string
            nullable: true
        - name: filter.service_tier
          in: query
          required: false
          description: 处理任务使用的服务等级。`default` 表示在线推理模式，`flex` 表示离线推理模式。
          schema:
            type: string
            nullable: true
            default: default
            enum:
              - default
              - flex
      responses:
        '200':
          description: 查询成功，返回符合筛选条件的视频生成任务列表。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVideoGenerationTasksResponse'
              examples:
                success:
                  summary: 查询成功
                  value:
                    total: 2
                    items:
                      - id: cgt-2026****-****
                        model: doubao-seedance-2-0-260128
                        status: succeeded
                        content:
                          video_url: >-
                            https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx
                        usage:
                          completion_tokens: 109586
                          total_tokens: 109586
                        created_at: 1779354227
                        updated_at: 1779354426
                        seed: 70172
                        resolution: 720p
                        ratio: '4:3'
                        duration: 5
                        framespersecond: 24
                        service_tier: default
                        execution_expires_after: 172800
                        generate_audio: true
                        draft: false
                        priority: 0
                      - id: cgt-2026****-****
                        model: doubao-seedance-2-0-260128
                        status: succeeded
                        content:
                          video_url: >-
                            https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx
                        usage:
                          completion_tokens: 49761
                          total_tokens: 49761
                        created_at: 1779353985
                        updated_at: 1779354268
                        seed: 68292
                        resolution: 480p
                        ratio: '3:4'
                        duration: 5
                        framespersecond: 24
                        service_tier: default
                        execution_expires_after: 172800
                        generate_audio: true
                        draft: false
                        priority: 0
        '400':
          description: 请求参数不合法。
        '401':
          description: 鉴权失败。
        '500':
          description: 服务端内部错误。
      security:
        - BearerAuth: []
components:
  schemas:
    ListVideoGenerationTasksResponse:
      type: object
      properties:
        items:
          type: array
          description: 查询到的视频生成任务列表。
          items:
            $ref: '#/components/schemas/VideoGenerationTask'
        total:
          type: integer
          description: 符合筛选条件的任务数量。
    VideoGenerationTask:
      type: object
      properties:
        id:
          type: string
          description: 视频生成任务 ID。
        model:
          type: string
          description: 任务使用的模型名称和版本，模型名称-版本。
        status:
          type: string
          description: |-
            任务状态。

            - queued：排队中。
            - running：任务运行中。
            - cancelled：取消任务（只支持排队中状态的任务被取消）。
            - succeeded：任务成功。
            - failed：任务失败。
            - expired：任务超时。
        error:
          $ref: '#/components/schemas/TaskError'
        created_at:
          type: integer
          description: 任务创建时间的 Unix 时间戳（秒）。
        updated_at:
          type: integer
          description: 任务当前状态更新时间的 Unix 时间戳（秒）。
        content:
          $ref: '#/components/schemas/VideoTaskContent'
        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 系列、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:
          $ref: '#/components/schemas/TaskUsage'
    TaskError:
      type: object
      nullable: true
      description: 错误提示信息。任务成功返回 null，任务失败时返回错误数据。
      properties:
        code:
          type: string
          description: 错误码。
        message:
          type: string
          description: 错误提示信息。
    VideoTaskContent:
      type: object
      description: 当视频生成任务完成，会输出该字段，包含生成视频下载的 URL。
      properties:
        video_url:
          type: string
          description: 生成视频的 URL。
        last_frame_url:
          type: string
          description: 视频的尾帧图像 URL。创建视频生成任务时设置 `return_last_frame=true` 时会返回参数。
    TaskTool:
      type: object
      properties:
        type:
          type: string
          description: |-
            实际使用的工具类型。

            - web_search：联网搜索工具。
    TaskUsage:
      type: object
      description: 本次请求的 token 用量。
      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:
          $ref: '#/components/schemas/ToolUsage'
    ToolUsage:
      type: object
      description: 使用工具的用量信息。
      properties:
        web_search:
          type: integer
          description: 实际调用联网搜索工具的次数，仅开启联网搜索时返回。
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: '在请求头中传入 `Authorization: Bearer <token>`。'

````