批量查询视频生成任务

本接口用于按条件批量查询视频生成任务列表，支持按状态、任务 ID、模型和服务等级等条件筛选，并支持分页返回。

提示

仅支持查询最近 7 天内创建的历史任务。时间范围以发起查询请求的时刻为基准，向前推算 7 天（精确到秒）。

请求方法

GET：<ai-api-base-url>/llm/v1/contents/generations/tasks

其中，<ai-api-base-url> 为您的 API Key 所属数据中心的域名：

• 北京数据中心：https://ai.rong-api.com
• 北美数据中心：https://ai.us-light-api.com

请求头参数

参数名	类型	是否必填	默认值	说明
Authorization	string	是	-	身份认证令牌，格式为 Bearer <your API key>，需替换为实际 API Key，用于验证用户权限。

Query 参数

以下参数通过 URL Query String 传入。

参数名	类型	是否必填	默认值	说明
page_num	integer	否	1	返回结果的页码。取值范围：[1, 500]。
page_size	integer	否	-	每页返回的结果数量。取值范围：[1, 500]。
filter.status	string	否	-	按任务状态筛选。可选值：queued（排队中）、running（运行中）、cancelled（已取消）、succeeded（已完成）、failed（已失败）。
filter.task_ids	string[]	否	-	按任务 ID 精确查询，支持同时查询多个。多个 ID 通过 & 连接，例如：filter.task_ids=id1&filter.task_ids=id2。
filter.model	string	否	-	按任务使用的模型接入标识精确筛选。该字段对应任务实际使用的模型或接入点标识，而不一定等同于展示名称。
filter.service_tier	string	否	default	按服务等级筛选。可选值：default、flex。

请求示例

cURL

bash

curl --request GET \
  --url '<ai-api-base-url>/llm/v1/contents/generations/tasks?page_num=1&page_size=10&filter.status=succeeded&filter.service_tier=default' \
  --header 'Authorization: Bearer <token>'

Python

python

import requests

url = "<ai-api-base-url>/llm/v1/contents/generations/tasks"
params = {
    "page_num": 1,
    "page_size": 10,
    "filter.status": "succeeded",
    "filter.service_tier": "default"
}
headers = {
    "Authorization": "Bearer <token>"
}

response = requests.get(url, params=params, headers=headers)
print(response.text)

JavaScript

JavaScript

const params = new URLSearchParams({
  page_num: 1,
  page_size: 10,
  'filter.status': 'succeeded',
  'filter.service_tier': 'default'
});

const options = {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>'
  }
};

fetch(`<ai-api-base-url>/llm/v1/contents/generations/tasks?${params}`, options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

返回结果

参数名	类型	是否必返	说明
items	object[]	是	查询到的视频生成任务列表。每个元素的字段结构与查询视频生成任务接口的返回体一致。
items[].id	string	是	任务 ID。
items[].model	string	是	执行任务所使用的模型名称。
items[].status	enum<string>	是	任务状态：queued、running、succeeded、failed、cancelled、expired。其中 cancelled 仅表示排队中任务被取消，expired 表示任务在排队或执行期间超过 execution_expires_after 阈值。
items[].error	object	否	任务失败时返回，包含错误详情。
items[].error.code	string	否	错误码。
items[].error.message	string	否	错误描述信息。
items[].created_at	integer	是	任务创建时间（Unix 时间戳，单位：秒）。
items[].updated_at	integer	是	任务最后更新时间（Unix 时间戳，单位：秒）。
items[].content	object	否	任务成功后返回，包含生成视频和尾帧等结果信息。
items[].content.video_url	string	否	视频下载地址（24 小时有效）。
items[].content.last_frame_url	string	否	尾帧图像地址（24 小时有效，仅 return_last_frame: true 时返回）。
items[].seed	integer	否	随机种子。
items[].resolution	string	否	视频分辨率，如 "720p"。
items[].ratio	string	否	视频宽高比，如 "16:9"。
items[].duration	integer	否	视频时长（单位：秒）。创建任务时未指定 frames 时返回。
items[].frames	integer	否	视频帧数。创建任务时按帧数控制长度时返回。
items[].framespersecond	integer	否	视频帧率（FPS）。
items[].generate_audio	boolean	否	是否包含同步音频。
items[].tools	object[]	否	本次任务实际使用的工具。
items[].tools[].type	string	否	工具类型。当前可能返回 web_search。
items[].safety_identifier	string	否	终端用户唯一标识符。若创建任务时设置了该字段，会原样返回。
items[].draft	boolean	否	当前输出是否为 Draft 视频。仅 Doubao/Doubao-seedance-1.5-pro 返回。
items[].draft_task_id	string	否	基于 Draft 视频生成正式视频时，对应的 Draft 视频任务 ID。
items[].service_tier	string	否	实际处理任务使用的服务等级。
items[].execution_expires_after	integer	否	任务超时阈值，单位：秒。
items[].usage	object	否	Token 用量统计。
items[].usage.completion_tokens	integer	否	输出 token 数量。对于 Seedance 2.0 系列模型，如果实际 token 用量低于最低计费门槛，则此字段返回最低计费对应的 token 数量，并按该值计费。
items[].usage.total_tokens	integer	否	总 token 数量。视频生成模型不统计输入 token，因此通常与 completion_tokens 相同。
items[].usage.tool_usage	object	否	工具用量信息。
items[].usage.tool_usage.web_search	integer	否	实际调用联网搜索工具的次数。
total	integer	是	符合筛选条件的任务总数量。

返回结果示例

JSON

{
  "items": [
    {
      "id": "cgt-2025xxxxxx-xxxx",
      "model": "Doubao/Doubao-seedance-2.0-fast",
      "status": "succeeded",
      "content": {
        "video_url": "https://example.com/generated-video.mp4",
        "last_frame_url": "https://example.com/last-frame.png"
      },
      "usage": {
        "completion_tokens": 246840,
        "total_tokens": 246840,
        "tool_usage": {
          "web_search": 1
        }
      },
      "created_at": 1765510475,
      "updated_at": 1765510559,
      "seed": 58944,
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5,
      "framespersecond": 24,
      "generate_audio": true,
      "tools": [
        {
          "type": "web_search"
        }
      ],
      "safety_identifier": "user_2f1c19a4d7",
      "service_tier": "default",
      "execution_expires_after": 172800
    }
  ],
  "total": 1
}