RealmDramaAPI 开发者文档
使用指南火山兼容APIOpenAI 兼容API在线调试帮助支持

查询视频生成任务列表

火山文档原文

GET /api/v3/contents/generations/tasks

GET
/api/v3/contents/generations/tasks

Authorization

BearerAuth

AuthorizationBearer <token>

输入 API Token。请求将使用 Authorization: Bearer 。

In: header

Query Parameters

page_num?integer

返回结果的页码

Default1
Range1 <= value <= 500
page_size?integer

每页显示的结果数量

Default20
Range1 <= value <= 500
filter.status?string

按任务状态筛选

Value in"queued" | "running" | "cancelled" | "succeeded" | "failed"
filter.task_ids?array<string>

按任务 ID 精确搜索。查询多个 ID 时重复传递参数名，例如 filter.task_ids=id1&filter.task_ids=id2

filter.model?string

按任务使用的推理接入点 ID 精确搜索；该值与响应中的模型名称不同

filter.service_tier?string

按服务等级筛选：default 为在线推理模式，flex 为离线推理模式

Default"default"
Value in"default" | "flex"

Response Body

application/json

application/json

application/json

curl -X GET "https://jieyun.cc/api/v3/contents/generations/tasks"
{
  "total": 30,
  "items": [
    {
      "id": "cgt-2026-example",
      "model": "doubao-seedance-2-0-260128",
      "status": "succeeded",
      "content": {
        "video_url": "https://example.com/generated-video.mp4"
      },
      "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
    }
  ]
}
{
  "error": {
    "message": "string",
    "type": "string",
    "param": "string",
    "code": "string"
  }
}
{
  "error": {
    "message": "string",
    "type": "string",
    "param": "string",
    "code": "string"
  }
}

接口说明

通过分页和筛选参数查询视频生成任务。本文档已按火山引擎官方接口说明校对。

GET https://jieyun.cc/api/v3/contents/generations/tasks
Authorization: Bearer <API_KEY>

查询范围与视频地址有效期

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

请求参数

本接口为 GET 请求，没有请求体。所有筛选条件均通过 Query 参数传递。

Query 参数类型默认值说明
page_numinteger1返回结果的页码，范围为 1–500。
page_sizeinteger20每页显示的结果数量，范围为 1–500。
filter.statusstring-任务状态：queued、running、cancelled、succeeded 或 failed。
filter.task_idsstring[]-按任务 ID 精确搜索。多个 ID 需要重复传递参数名。
filter.modelstring-按推理接入点 ID 精确搜索。该值与响应中的模型名称不同。
filter.service_tierstringdefault服务等级：default 为在线推理，flex 为离线推理。

查询多个任务 ID：

filter.task_ids=id1&filter.task_ids=id2

请求示例：

curl -X GET "https://jieyun.cc/api/v3/contents/generations/tasks?page_size=3&filter.status=succeeded" \
  -H "Authorization: Bearer <API_KEY>"

响应内容

响应根对象包含：

字段类型说明
totalinteger符合筛选条件的任务数量。
itemsobject[]查询到的视频生成任务列表。

每个 items 元素可能包含：

字段类型说明
idstring视频生成任务 ID。
modelstring任务使用的模型名称和版本。
statusstringqueued、running、cancelled、succeeded、failed 或 expired。
errorobject / null成功时为 null；失败时包含 code 和 message。
created_atinteger任务创建时间的 Unix 时间戳（秒）。
updated_atinteger任务状态更新时间的 Unix 时间戳（秒）。
content.video_urlstring生成视频 URL，有效期为 24 小时。
content.last_frame_urlstring尾帧图像 URL；创建任务时设置 return_last_frame: true 才返回，有效期为 24 小时。
seedinteger本次请求使用的种子整数值。
resolutionstring生成视频的分辨率。
ratiostring生成视频的宽高比。
durationinteger视频时长（秒）；与 frames 只返回一个。
framesinteger视频帧数；创建任务时指定 frames 才返回。
framespersecondinteger视频帧率。
generate_audioboolean是否包含与画面同步的声音。
toolsobject[]模型实际使用的工具；当前工具类型包括 web_search。
safety_identifierstring创建任务时设置的终端用户唯一标识符。
priorityinteger当前请求的执行优先级。
draftboolean是否为 Draft 视频。
draft_task_idstring基于 Draft 视频生成正式视频时返回的 Draft 任务 ID。
service_tierstring实际处理任务使用的服务等级。
execution_expires_afterinteger任务超时阈值（秒）。
usage.completion_tokensinteger模型生成视频消耗的 token 数量，可用于计费对账。
usage.total_tokensinteger总 token 数量；视频任务中等于 completion_tokens。
usage.tool_usage.web_searchinteger实际调用联网搜索工具的次数。

查询视频生成任务 API

GET /api/v3/contents/generations/tasks/{task_id}

取消或删除视频生成任务

DELETE /api/v3/contents/generations/tasks/{task_id}