Seedance 接口格式生视频

本文介绍创建视频生成任务 API 的输入输出参数，供您使用接口时查阅字段含义。模型会依据传入的图片及文本信息生成视频，待生成完成后，您可以按条件查询任务并获取生成的视频。

项目	说明
请求方法	`POST`
接口地址	`https://api.taiha.cn/v1/video/generations`
鉴权	请求头 `Authorization: Bearer`
Model ID	在模型广场对应模型详情中查看

重要说明

本Seedance接口完全支持豆包官方接口请求体，在请求创建视频任务时，请求体可完全按照火山官方文档说明进行构造

模型能力

Doubao Seedance 2.5 （有声视频 / 无声视频）

全模态参考生视频：输入参考图片（0-30 张）+ 参考视频（0-10 个）+ 参考音频（0-10 个）+ 文本提示词（可选）生成 1 个目标视频。支持仅传入音频。支持生成全新视频、编辑视频、延长视频，支持 30 秒视频连贯直出。
图生视频-首尾帧：输入首帧图片 + 尾帧图片 + 文本提示词（可选）生成 1 个目标视频。
图生视频-首帧：输入首帧图片 + 文本提示词（可选）生成 1 个目标视频。
文生视频：输入文本提示词生成 1 个目标视频。

Doubao Seedance 2.0 系列

全模态参考生视频：输入参考图片（0-9 张）+ 参考视频（0-3 个）+ 参考音频（0-3 个）+ 文本提示词（可选）生成 1 个目标视频。注意不可单独输入音频，应至少包含 1 个参考视频或图片。支持生成全新视频、编辑视频、延长视频。
图生视频-首尾帧：输入首帧图片 + 尾帧图片 + 文本提示词（可选）生成 1 个目标视频。
图生视频-首帧：输入首帧图片 + 文本提示词（可选）生成 1 个目标视频。
文生视频：输入文本提示词生成 1 个目标视频。

1. 生成视频任务

POST /v1/video/generations

cURL
Python

curl -X POST 'https://api.taiha.cn/v1/video/generations' \
-H 'Authorization: Bearer <API Key>' \
-H 'Content-Type: application/json' \
-d '{
    "model": "<Model ID>",
    "content": [{
      "type": "text",
      "text": "明亮多彩的广告片风格，果味饼干为主角，包含草莓、苹果、葡萄、橙子四种口味，草莓味参考@图像1，饼干与对应水果以强秩序感的几何阵列排布，整体画面干净、高级、节奏强。开场水果快速建立视觉聚焦，参考@视频1的构图，音乐重拍切入。随后不同口味饼干整齐排列，切特写，参考@视频2的动态和运镜。高潮段一块饼干被折断，瞬间进入慢动作，果味夹心爆开，碎屑飞溅，果汁感与颗粒冲击被放大展示，参考@视频3的冲击感。横向阵列，形成节奏抛物感，参考@视频4的运动，突出秩序美感与产品丰富度。随后迅速回到快节奏剪辑。结尾英文文字 One bite of crispness, a heart full of delight 快速分词切换入画，配合强节奏文字运动与产品定格，参考@视频5，最终品牌感收束，饼干和水果向四周发散，参考@视频6画面充满年轻、活力、好吃、想分享的广告氛围。"
    }, {
      "type": "image_url",
      "image_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/images/video-generation/seedance2.5_reference1.png"
      },
      "role": "reference_image"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference2.mp4"
      },
      "role": "reference_video"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference3.mp4"
      },
      "role": "reference_video"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference4.mp4"
      },
      "role": "reference_video"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference5.mp4"
      },
      "role": "reference_video"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference6.mp4"
      },
      "role": "reference_video"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference7.mp4"
      },
      "role": "reference_video"
    }],
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 15
    }
}'

import requests
url = "https://api.taiha.cn/v1/video/generations"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}
payload = {
    "model": "<Model ID>",
    "content": [{
      "type": "text",
      "text": "明亮多彩的广告片风格，果味饼干为主角，包含草莓、苹果、葡萄、橙子四种口味，草莓味参考@图像1，饼干与对应水果以强秩序感的几何阵列排布，整体画面干净、高级、节奏强。开场水果快速建立视觉聚焦，参考@视频1的构图，音乐重拍切入。随后不同口味饼干整齐排列，切特写，参考@视频2的动态和运镜。高潮段一块饼干被折断，瞬间进入慢动作，果味夹心爆开，碎屑飞溅，果汁感与颗粒冲击被放大展示，参考@视频3的冲击感。横向阵列，形成节奏抛物感，参考@视频4的运动，突出秩序美感与产品丰富度。随后迅速回到快节奏剪辑。结尾英文文字 One bite of crispness, a heart full of delight 快速分词切换入画，配合强节奏文字运动与产品定格，参考@视频5，最终品牌感收束，饼干和水果向四周发散，参考@视频6画面充满年轻、活力、好吃、想分享的广告氛围。"
    }, {
      "type": "image_url",
      "image_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/images/video-generation/seedance2.5_reference1.png"
      },
      "role": "reference_image"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference2.mp4"
      },
      "role": "reference_video"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference3.mp4"
      },
      "role": "reference_video"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference4.mp4"
      },
      "role": "reference_video"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference5.mp4"
      },
      "role": "reference_video"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference6.mp4"
      },
      "role": "reference_video"
    }, {
      "type": "video_url",
      "video_url": {
        "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference7.mp4"
      },
      "role": "reference_video"
    }],
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 15
    }
response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)
}

请求参数

model 　string　必填　|　模型ID

模型ID，请按照模型广场中模型所示名称填写，区分大小写。
您也可以通过请求端点models来获得所有可请求的模型列表。

content 　object　必填　|　输入内容列表

输入给模型生成视频的信息，支持文本、图片、音频、视频、样片任务 ID 等多种类型的元素。
支持以下几种组合：

纯文本
文本（可选）+ 图片
文本（可选）+ 视频
文本（可选）+ 音频（仅 Seedance 2.5 支持单独传入音频）
文本（可选）+ 图片 + 音频
文本（可选）+ 图片 + 视频
文本（可选）+ 视频 + 音频
文本（可选）+ 图片 + 视频 + 音频
样片任务 ID：样片指使用 Seedance 模型成功生成的样片视频，模型可基于样片生成高质量正式视频

文本信息　object

文本部分，作为生成内容的文本提示词。

text 　string　必填　|　文本提示词

输入给模型的文本提示词，描述期望生成的视频。

说明

提示词语言支持：所有模型均支持中英文提示词；

Seedance 2.5 ：额外支持西班牙语、印度尼西亚语、葡萄牙语、日语、马来语、泰语、阿拉伯语、越南语、韩语；

Seedance 2.0 系列：额外支持西班牙语、印度尼西亚语、葡萄牙语、日语。

提示词字数建议：中文提示词不超过 500 字，英文提示词不超过 1000 词。字数过多易导致信息分散，模型可能忽略细节、仅关注重点，进而造成视频缺失部分元素。

type 　string　必填　|　内容类型

输入内容的类型，此处固定为 text。

图片信息　object

输入给模型的图片信息。

image_url 　object　必填　|　图片对象

输入给模型的图片对象。

url 　string　必填　|　图片来源

图片 URL、图片 Base64 编码、素材 ID。

图片 URL ：填入图片的公网 URL。
Base64 编码 ：将本地文件转换为 Base64 编码字符串后提交给大模型，遵循格式 data:image/<图片格式>;base64,<Base64 编码>，注意 <图片格式> 需小写，如 data:image/png;base64,{base64_image}。
素材 ID ：用于视频生成的预置素材及虚拟人像的 ID，遵循格式 asset://<ASSET_ID>。可从素材 & 虚拟人像库获取。

图片格式要求

格式：jpeg、png、webp、bmp、tiff、gif。其中，Seedance 1.5 pro 及以上模型版本额外支持 heic、heif。

宽高比（宽/高） ：[0.4, 2.5]

宽高长度（px） ：[300, 6000]

大小：单张图片小于 30 MB。请求体大小不超过 64 MB。大文件请勿使用 Base64 编码。

图片数量 ：

图生视频-首帧 ：1 张

图生视频-首尾帧 ：2 张

Seedance 2.5 全模态参考生视频 ：1-30 张

Seedance 2.0 系列全模态参考生视频 ：1-9 张

type 　string　必填　|　内容类型

输入内容的类型，此处固定为 image_url。

role 　string　必填　|　角色/用途

图片的位置或用途。

图生视频-首帧

字段 role 取值：需要传入 1 个 image_url 对象，role 为 first_frame 或不填。

图生视频-首尾帧

字段role取值：需要传入 2 个 image_url 对象，且 role 必填。

首帧图片对应的 role 为 first_frame
尾帧图片对应的 role 为 last_frame

传入的首尾帧图片可相同。首尾帧图片的宽高比不一致时，以首帧图片为主，尾帧图片会自动裁剪适配。

图生视频-参考图

字段role取值：必填，每张参考图对应的 role 均为 reference_image。

图生视频-首帧、图生视频-首尾帧、全模态参考生视频（包括参考图、视频、音频）为 3 种互斥场景，不可混用。全模态参考生视频可通过提示词指定参考图片作为首帧 / 尾帧，间接实现「首尾帧 + 全模态参考」效果。若需严格保障首尾帧和指定图片一致，优先使用图生视频-首尾帧（配置 role 为 first_frame / last_frame）。

视频信息　object

输入给模型的视频信息。

doubao接口只信任 Seedance 2.5、Seedance 2.0 系列模型生成的含人脸视频，您可使用 相同账号下30 天内由上述模型生成的含人脸原始视频，作为输入素材进行二次创作。

type 　string　必填　|　内容类型

输入内容的类型，此处固定为 video_url。

video_url 　object　必填　|　视频对象

输入给模型的视频对象。

url 　string　必填　|　视频来源

视频 URL、素材 ID。

视频 URL ：填入视频的公网 URL。
素材 ID ：用于视频生成的预置素材及虚拟人像视频的 ID，遵循格式 asset://<ASSET_ID>。请参考素材 & 虚拟人像库获取。

传入单个视频要求

视频格式 ：mp4、mov，支持编码格式见下表。

分辨率 ：480p、720p、1080p、4k

时长：

Seedance 2.5 ：

非视频编辑任务：单个视频时长 [2, 30] s。

视频编辑任务：单个视频时长 [4, 30] s。

最多传入 10 个参考视频，所有视频总时长不超过 30 s。

Seedance 2.0 系列 ：单个视频时长 [2, 15] s，最多传入 3 个参考视频，所有视频总时长不超过 15 s。

尺寸：

宽高比（宽/高） ：[0.4, 2.5]

宽高长度（px） ：[300, 6000]

总像素数 ：[614×664=407696, 3326×2494=8295044]，即宽和高的乘积符合 [407696, 8295044] 的区间要求。

大小：单个视频不超过 200 MB。

帧率（FPS） ：[24, 60]

role 　string　必填　|　角色/用途

视频的位置或用途，此处固定为 reference_video。

音频信息　object

用作参考音频。

Seedance 2.5：可仅传入音频，无需搭配图片 / 视频；也可配合图片 / 视频一起传入 Seedance 2.0 系列：不可单独输入音频，应至少包含 1 个参考视频或图片。

audio_url 　object　必填　|　音频对象

输入给模型的音频对象。

url 　string　必填　|　音频来源

音频 URL、音频 Base64 编码、素材 ID。

音频 URL ：填入音频的公网 URL。
Base64 编码 ：将本地文件转换为 Base64 编码字符串后提交给大模型，遵循格式 data:audio/<音频格式>;base64,<Base64 编码>，注意 <音频格式> 需小写，如 data:audio/wav;base64,{base64_audio}。
素材 ID ：用于视频生成的虚拟人的音频素材 ID，遵循格式 asset://<ASSET_ID>。可参考素材 & 虚拟人像库获取。

传入单个音频要求

格式：wav、mp3

时长：

Seedance 2.5 ：单个音频时长 [2, 30] s，最多传入 10 段参考音频，所有音频总时长不超过 30 s。

Seedance 2.0 系列 ：单个音频时长 [2, 15] s，最多传入 3 段参考音频，所有音频总时长不超过 15 s。

大小：单个音频不超过 15 MB，请求体大小不超过 64 MB。大文件请勿使用 Base64 编码。

type 　string　必填　|　内容类型

输入内容的类型，此处固定为 audio_url。

role 　string　必填　|　角色/用途

音频的位置或用途，此处固定为 reference_audio。

execution_expires_after 　integer　默认值 172800　|　任务超时阈值

任务超时阈值。指定任务提交后的过期时间（单位：秒），从 created_at 时间戳开始计算，默认 48 小时。

超过该时间后任务会被自动终止，并标记为 expired 状态。

不论使用哪种 service_tier，都建议根据业务场景设置合适的超时时间。

取值范围 ：[3600, 259200]

generate_audio 　boolean　默认值 true　|　生成有声视频

控制生成的视频是否包含与画面同步的声音。

true：模型输出的视频包含同步音频，模型会基于文本提示词与视觉内容自动生成匹配的人声、音效及背景音乐。建议将对话部分置于双引号内以优化音频生成效果，例如：男人叫住女人说："你记住，以后不可以用手指指月亮。"
false：模型输出的视频为无声视频。

生成的有声视频均为单声道，和传入的音频声道数无关。

omni_reference_task_type 　string　默认值 auto　|　任务类型引导

Seedance 2.5 全模态参考生视频任务 包括参考生视频、视频编辑和视频延长 3 类子任务。不同任务类型对参数有特殊限制，为减少任务创建后异步报错的情况，可通过本参数指定子任务类型，以提前校验对应限制。

默认情况下，即 omni_reference_task_type=auto：模型根据输入素材和提示词自动判定任务类型，再校验参数取值。如果参数与实际任务类型不兼容，任务将触发 异步报错（错误码：InvalidParameter.TaskTypeConstraint）。
显式指定任务类型，即 omni_reference_task_type 为 reference、edit 或 extend：接口在提交任务时提前校验对应任务的特殊参数限制。不符合要求时，接口立即报错，任务不会创建。

注意

实际处理任务时，模型仍会进一步结合提示词判断任务类型。若实际判定的任务类型和指定的不一致，仍会触发异步报错（错误码：InvalidParameter.TaskTypeMismatch）。建议遵循各任务类型的提示词写法，降低报错概率。

可选值：

auto：由模型根据输入素材和提示词自动判定任务类型。
reference：参考生视频任务，即基于参考图片、参考视频或参考音频生成新视频。设置 reference 时，ratio 或 duration 无特殊限制。
edit：视频编辑任务，即对原视频的画面或音频进行编辑操作。设置 edit 时，content 中必须至少包含一个 reference_video，且视频时长必须为 4–30 秒；ratio 必须为 adaptive；duration 必须为 -1。
extend：视频延长任务，即对原视频向前或向后延长。设置 extend 时，content 中必须至少包含一个 reference_video；ratio 必须为 adaptive。

模型支持 ：

Seedance 2.5

output_format 　string　默认值 mp4　|　输出格式

输出视频的格式。

mp4：通用格式，兼容性最好，采用标准色彩精度，可在网页、移动端、各类播放器及分发平台直接播放。
mov：面向专业场景的高色彩精度格式，更好地保持画面色彩与亮度一致性、适用于调色、抠像、合成等对色彩还原要求高的专业后期加工。推荐在视频编辑、视频延长场景使用 mov 格式作为输入和输出。

mov 格式播放兼容性

mov 格式采用专业编码（H.264视频编码+yuv444p 色度采样+PCM 音频编码），部分播放器可能不兼容。以下为常见的支持播放 mov 格式的播放器：

播放器	macOS	Windows
IINA	✓	✕
VLC	✓	✓
mpv	✓	✓
ffplay	✓	✓

模型支持 ：

Seedance 2.5

draft 　boolean　默认值 false　|　样片模式

控制是否开启样片模式。

true：开启样片模式，生成一段预览视频，用于确认场景结构、镜头调度、主体动作与 Prompt 意图是否符合预期。
false：关闭样片模式，正常生成一段视频。

说明

开启样片模式后，仅支持生成 480p 分辨率的 Draft 视频（使用其他分辨率会报错）。
参数限制和计费方式详见 Seedance 2.5 样片模式。

模型支持：

Seedance 2.5

priority 　integer　默认值 0　|　执行优先级

设置当前请求的执行优先级，决定其在队列中的排序位置。数值越大，优先级越高。默认情况下，请求按 FIFO（First In, First Out，先进先出）顺序执行；设置较高优先级后，该请求将插队到同 Endpoint（推理接入点）下所有低优先级请求之前。示例：某 Endpoint 当前队列中有 3 个排队中（status=queued）任务，优先级均为 0（默认）：

队列：[任务A: priority=0] → [任务B: priority=0] → [任务C: priority=0]

此时提交一个 priority=5 的新请求，该请求将直接排到队首：

队列：[新请求: priority=5] → [任务A: priority=0] → [任务B: priority=0] → [任务C: priority=0]

注意

相同优先级的请求之间仍按 FIFO 排序。
优先级仅影响排队顺序，不会中断正在执行中（status=running）的任务。
优先级仅在同一 Endpoint 内生效，不影响其他 Endpoint。
离线推理模式（service_tier=flex）不支持配置优先级。

取值范围 ：[0, 9]

模型支持 ：

Seedance 2.5
Seedance 2.0 系列

duration 　integer　必填　|　视频时长

生成视频时长（单位：秒）。

duration 和 frames 二选一即可，frames 优先级更高。如果您希望生成整数秒的视频，建议指定 duration。

当 duration 设置为 -1 时，实际生成视频的时长可通过查询视频生成任务 API 返回的 duration 字段获取。视频时长与计费相关，请谨慎设置。

模型	duration = -1取值规则
Seedance 2.0 系列	模型在 duration 的有效取值范围内，自主选择合适的视频长度（整数秒）。
Seedance 2.5（视频编辑任务）	自动保持输出视频和输入视频的时长基本一致（输出时长可能略短于输入视频，误差约 0.4 秒），不支持另行设置。
Seedance 2.5（其他任务类型）	模型在 duration 的有效取值范围内，自主选择合适的视频长度（整数秒）。

Seedance 2.5 模型在视频编辑任务的限制条件：

仅支持配置duration为 -1，不支持指定具体输出时长。
传入的待编辑视频时长需在 [4, 30]s 内，否则将触发报错。

ratio 　string　必填　|　视频宽高比

生成视频的宽高比例。

可选值：16:9、4:3、1:1、3:4、9:16、21:9、adaptive（根据任务类型和输入内容自动适配宽高比）

注意

Seedance 2.5 模型在视频编辑、视频延长、首帧 / 首尾帧生视频任务的限制条件：
仅支持配置ratio为 adaptive，不支持指定具体宽高比。

resolution 　string　默认值 720p　|　视频分辨率

视频分辨率。可选值：480p、720p、1080p、4k。

注意

相较于一般的 8bit 位深，Seedance 2.0 输出的 4k 视频采用 10bit 位深编码，能够完整保留丰富的色彩层次与平滑的渐变过渡，满足专业影视制作与 HDR 视频内容的要求。
4K 视频采用 H.265 编码，少数播放环境可能不兼容，如遇问题，建议升级系统、更换设备或使用 VLC、MPV、QuickTime Player 等播放器查看。

模型支持 ：

Seedance 2.5 ：默认值 720p；可选值 480p、720p
Seedance 2.0 ：默认值 720p；可选值 480p、720p、1080p、4k
Seedance 2.0 fast ：默认值 720p；可选值 480p、720p
Seedance 2.0 mini ：默认值 720p；可选值 480p、720p

return_last_frame 　boolean　默认值 false　|　返回尾帧

是否返回生成视频的尾帧图像。

true：返回生成视频的尾帧图像，可通过查询视频生成任务接口获取，尾帧图像的格式为 png，宽高像素值与生成的视频保持一致，无水印。
false：不返回生成视频的尾帧图像。

使用该参数可实现生成多个连续视频：以上一个生成视频的尾帧作为下一个视频任务的首帧，快速生成多个连续视频。

safety_identifier 　string　可选　|　用户标识

终端用户的唯一标识符，用于协助平台检测您的应用中可能违反火山方舟使用政策的用户。该标识符为英文字符串，需保证对单个用户固定且唯一，长度不超过 64 个字符。推荐传入对用户名、用户 ID 或邮箱进行哈希处理后生成的字符串，避免泄露用户隐私信息。

tools 　object[]　可选　|　工具配置

配置模型要调用的工具。
模型支持：

Seedance 2.5
Seedance 2.0 系列

type 　string　必填　|　工具类型

指定使用的工具类型。

watermark 　boolean　默认值 false　|　视频水印

生成视频是否包含水印。

true：生成视频右下角会展示 AI 生成水印。
false：生成视频不含水印。

响应参数

task_id 　string　|　任务 ID

视频生成任务 ID。仅保存 7 天（从 created_at 时间戳开始计算），超时后将自动清除。

设置 "draft": true，为 Draft 视频任务 ID。
设置 "draft": false，为正常视频任务 ID。

创建视频生成任务为 异步接口 ，获取 ID 后需要通过查询视频生成任务 API 来查询任务状态。任务成功后会输出生成视频的 video_url。

响应示例

{
  "id":"task_lFAPGYCrZRAiH4We5EGfRlcMeZ5NpT7C",
  "task_id":"task_lFAPGYCrZRAiH4We5EGfRlcMeZ5NpT7C",
  "object":"video",
  "model":"doubao-seedance-2.0-mini",
  "status":"queued",
  "progress":0,
  "created_at":1786713281
}

注意

请求后并不会立即返回生成内容，耗时取决于prompt复杂程度及分辨率等要求，通常需要100秒左右。您可以通过任务查询接口获取生成进度及结果。

2. 查询单个任务（实时）

GET /v1/video/generations/{task_id}

两个路径等价，前者为 ark 官方风格，后者为 OpenAI 风格。

curl "https://token.taiha.cn/v1/video/generations/task_xxx" \
  -H "Authorization: Bearer sk-xxxxxxxx"

返回任务当前状态与结果（成功时含 content.video_url）。

3. 查询任务列表

GET /v1/video/generations/tasks

两个路径等价。数据来源为本地任务记录快照（轮询器持续同步上游状态，最长约 15 秒延迟）；需要实时状态请用第 1 节的单任务查询。

Query 参数

参数	类型	必填	默认	说明
`filter.model`	string	否	-	按模型名精确筛选（提交任务时的模型名，如 `doubao-seedance-2.0-mini`）
`filter.status`	string	否	-	任务状态：`queued` / `running` / `succeeded` / `failed` / `cancelled`
`filter.task_ids`	string[]	否	-	按任务 ID 精确查询，可重复传多个
`page_num`	int	否	`1`	页码
`page_size`	int	否	`20`	每页数量，上限 `500`

cancelled 筛选说明：与官方一致作为独立筛选项；因平台内 cancelled 与 failed 同存储为失败终态，该筛选会同时返回这两类记录（响应中会正确区分）。

响应字段

{
  "items": [
    {
      "id": "task_xxx",
      "model": "doubao-seedance-2.0-mini",
      "status": "succeeded",
      "created_at": 1758000000,
      "content": { "video_url": "https://..." },
      "usage": { "completion_tokens": 123 },
      "error": { "message": "失败原因" }
    }
  ],
  "total": 42
}

字段	说明
`items[].id`	平台任务 ID
`items[].model`	提交时的模型名
`items[].status`	`queued` / `running` / `succeeded` / `failed` / `cancelled`
`items[].created_at`	创建时间（Unix 秒）
`items[].content.video_url`	成功时的视频地址（未完成为空）
`items[].usage.completion_tokens`	成功时的用量 tokens
`items[].error.message`	仅失败/取消任务返回
`total`	符合筛选条件的任务总数

请求示例

# 基础查询（第 1 页，每页 20 条）
curl "https://token.taiha.cn/v1/video/generations/tasks" \
  -H "Authorization: Bearer sk-xxxxxxxx"

# 按状态筛选排队中的任务
curl "https://token.taiha.cn/v1/video/generations/tasks?filter.status=queued" \
  -H "Authorization: Bearer sk-xxxxxxxx"

# 按模型 + 状态组合筛选
curl "https://token.taiha.cn/v1/video/generations/tasks?filter.model=doubao-seedance-2.0-mini&filter.status=succeeded" \
  -H "Authorization: Bearer sk-xxxxxxxx"

# 按多个任务 ID 精确查询
curl "https://token.taiha.cn/v1/video/generations/tasks?filter.task_ids=task_aaa&filter.task_ids=task_bbb" \
  -H "Authorization: Bearer sk-xxxxxxxx"

# 翻页：第 2 页，每页 50 条（OpenAI 风格路径）
curl "https://token.taiha.cn/v1/videos?page_num=2&page_size=50" \
  -H "Authorization: Bearer sk-xxxxxxxx"

响应示例

{
  "items": [
    {
      "id": "task_tl5DZPExR3whw6jeeFc5GRejDlPPVQsh",
      "model": "doubao-seedance-2.0-mini",
      "status": "succeeded",
      "created_at": 1790048932,
      "content": {
        "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/....mp4?X-Tos-..."
      },
      "usage": { "completion_tokens": 1050 }
    },
    {
      "id": "task_7gZ8XOAjEbGzutljKypRFAw9ZzMqiz6Z",
      "model": "doubao-seedance-2.0-mini",
      "status": "failed",
      "created_at": 1790048000,
      "content": { "video_url": "" },
      "usage": { "completion_tokens": 0 },
      "error": { "message": "upstream returned error" }
    }
  ],
  "total": 2
}

错误响应

{ "error": { "message": "查询任务列表失败" } }

与官方 ark 接口的差异

项	官方	本平台
时间范围	仅最近 7 天	不限（全量历史记录）
`filter.service_tier`	支持	不支持（忽略）
数据实时性	实时	轮询快照（约 15 秒内延迟）

4. 取消 / 删除任务

DELETE /v1/video/generations/{task_id}

两个路径等价。行为由任务当前状态决定（与火山 ark 官方语义对齐）：

任务状态	行为	退款
`queued`（排队中）	向上游发送取消 → 二次确认 → 置终态	预扣费原路退还
`running`（运行中）	落取消标记，系统每 3 秒重试；命中排队窗口自动取消退款；跑完则正常计费	取消成功时
`succeeded` / `failed` / `expired` / `cancelled`（终态）	向上游删除任务记录（后续上游无法查询），本地记录保留作计费凭证	否（已结算）
已删除过	幂等，直接返回成功	—

请求示例

curl -X DELETE "https://token.taiha.cn/v1/video/generations/task_xxx" \
  -H "Authorization: Bearer sk-xxxxxxxx"

响应

统一 HTTP 200，通过 success 字段区分结果。

取消排队中任务成功（额度已退，状态变为 cancelled）：

{ "success": true, "message": "", "data": null }

任务运行中（已标记取消请求）：

{
  "success": true,
  "message": "",
  "data": {
    "message": "任务运行中暂无法取消，已为您标记取消请求：系统将持续检测，一旦任务回到排队状态即自动取消并退款；若任务持续运行至完成，将正常计费，无法退款"
  }
}

可重复调用（幂等）。

终态任务删除上游记录成功：

{
  "success": true,
  "message": "",
  "data": { "message": "已删除上游任务记录，本地记录保留作为计费凭证" }
}

终态任务重复删除（幂等）：

{ "success": true, "message": "", "data": { "message": "上游任务记录已删除" } }

失败场景：

{ "success": false, "message": "任务不存在" }
{ "success": false, "message": "任务已结束，无法取消" }
{ "success": false, "message": "向上游取消任务失败，请稍后再试" }
{ "success": false, "message": "删除上游任务记录失败，请稍后再试" }
{ "success": false, "message": "当前平台不支持删除上游任务记录" }
{ "success": false, "message": "仅排队中的任务支持取消" }

错误消息	含义
`任务已结束，无法取消`	本地非终态但上游已完成（等待轮询结算后可再删）
`向上游取消任务失败，请稍后再试`	上游状态查询或 DELETE 报错，可重试
`当前平台不支持删除上游任务记录`	任务所属平台未实现上游删除能力（目前支持 doubao/seedance）
`仅排队中的任务支持取消`	上游状态未知，未产生任何变更

完整调用流程示例

# 1. 提交任务
curl -X POST "https://token.taiha.cn/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"model": "doubao-seedance-2.0-mini", "content": [...]}'
# → {"id": "task_tl5DZPExR3whw6jeeFc5GRejDlPPVQsh", ...}

# 2. 立即取消（排队窗口内 → 退款）
curl -X DELETE "https://token.taiha.cn/v1/video/generations/task_tl5DZPExR3whw6jeeFc5GRejDlPPVQsh" \
  -H "Authorization: Bearer sk-xxxxxxxx"

# 3. 确认状态已变为 cancelled
curl "https://token.taiha.cn/v1/video/generations/tasks?filter.task_ids=task_tl5DZPExR3whw6jeeFc5GRejDlPPVQsh" \
  -H "Authorization: Bearer sk-xxxxxxxx"

# 4. 任务完成后删除上游记录
curl -X DELETE "https://token.taiha.cn/v1/videos/task_tl5DZPExR3whw6jeeFc5GRejDlPPVQsh" \
  -H "Authorization: Bearer sk-xxxxxxxx"

注意事项

排队窗口极短：官方确认 queued → running 由服务端瞬间调度，建议拿到 task_id 后第一时间发 DELETE，不要等轮询确认 queued 再取消
running 不可强制取消：官方语义，运行中的算力已实际消耗
取消成功以二次查询为准：网关已内置 DELETE 后二次确认（防上游静默 no-op 误判），客户端可再查列表确认 status=cancelled
终态删除不退款：删除记录仅清理上游侧数据，结算事实不变

模型能力​

1. 生成视频任务​

请求参数​

响应参数​

响应示例​

2. 查询单个任务（实时）​

3. 查询任务列表​

Query 参数​

响应字段​

请求示例​

响应示例​

错误响应​

与官方 ark 接口的差异​

4. 取消 / 删除任务​

请求示例​

响应​

完整调用流程示例​

注意事项​

模型能力

1. 生成视频任务

请求参数

响应参数

响应示例

2. 查询单个任务（实时）

3. 查询任务列表

Query 参数

响应字段

请求示例

响应示例

错误响应

与官方 ark 接口的差异

4. 取消 / 删除任务

请求示例

响应

完整调用流程示例

注意事项