curl --fail-with-body --silent --show-error \
--request POST \
--url https://code.heihuzi.ai/api/v3/contents/generations/tasks \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "一只手从枝头摘下沾着露水的红苹果,阳光透过树叶,镜头缓慢推近"},
{"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"}, "role": "first_frame"}
],
"resolution": "480p",
"ratio": "adaptive",
"duration": 5
}'
{"id":"cgt-20261005170037-c27t7"}
Seedance 视频
Seedance 视频:创建任务
用 Seedance 2.0、2.0 Fast、2.0 mini、2.5 异步生成视频,支持文生视频、首帧、首尾帧、参考图和参考视频。
POST
/
api
/
v3
/
contents
/
generations
/
tasks
curl --fail-with-body --silent --show-error \
--request POST \
--url https://code.heihuzi.ai/api/v3/contents/generations/tasks \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "一只手从枝头摘下沾着露水的红苹果,阳光透过树叶,镜头缓慢推近"},
{"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"}, "role": "first_frame"}
],
"resolution": "480p",
"ratio": "adaptive",
"duration": 5
}'
{"id":"cgt-20261005170037-c27t7"}
POST https://code.heihuzi.ai/api/v3/contents/generations/tasks 创建一个 Seedance 视频生成任务,请求和响应的格式与火山方舟「创建视频生成任务」接口相同。任务异步执行:创建后返回 id,再用查询任务获取成片链接;已结束的任务可以删除。
请使用绑定「Seedance 视频」分组的 API Key。其他分组的 Key 调用会返回 403 PermissionDenied。
curl --fail-with-body --silent --show-error \
--request POST \
--url https://code.heihuzi.ai/api/v3/contents/generations/tasks \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "一只手从枝头摘下沾着露水的红苹果,阳光透过树叶,镜头缓慢推近"},
{"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"}, "role": "first_frame"}
],
"resolution": "480p",
"ratio": "adaptive",
"duration": 5
}'
HEIHUZI_API_KEY。上面的示例用一张图作为视频的第一帧。
模型
| 模型 ID | 名称 | 清晰度 | 时长 |
|---|---|---|---|
doubao-seedance-2-0-260128 | Seedance 2.0 | 480p、720p、1080p、4k | 4–15 秒 |
doubao-seedance-2-0-fast-260128 | Seedance 2.0 Fast | 480p、720p | 4–15 秒 |
doubao-seedance-2-0-mini-260615 | Seedance 2.0 mini | 480p、720p | 4–15 秒 |
doubao-seedance-2-5-260628 | Seedance 2.5 | 480p、720p、1080p | 4–30 秒 |
| 模型 | 参考图 | 参考视频 |
|---|---|---|
| Seedance 2.0、2.0 Fast、2.0 mini | 最多 9 张 | 最多 3 个,合计不超过 15 秒 |
| Seedance 2.5 | 最多 30 张 | 最多 10 个,合计不超过 30 秒 |
请求参数
输入内容列表,不能为空。首帧、首尾帧、参考素材(参考图、参考视频)是三种互斥的用法,不能混用。
- 文字:
{"type": "text", "text": "画面与动作描述"}。 - 首帧:
{"type": "image_url", "image_url": {"url": "图片链接"}, "role": "first_frame"}。 - 首尾帧:再加一张
"role": "last_frame"的图片,视频从首帧过渡到尾帧。 - 参考图:
{"type": "image_url", "image_url": {"url": "图片链接"}, "role": "reference_image"},数量上限见上表。 - 参考视频:
{"type": "video_url", "video_url": {"url": "视频链接"}, "role": "reference_video"},数量和时长上限见上表,可以和参考图一起用。
清晰度:
480p、720p、1080p、4k,各模型可选的清晰度见上表。选了模型不支持的清晰度返回 400 PricingNotConfigured。清晰度越高,用量越大。Seedance 2.5 的 1080p 和 Seedance 2.0 的 4k 成片是 10bit、H.265 编码,少数播放环境可能需要换播放器查看。画面比例:
16:9、4:3、1:1、3:4、9:16、21:9,或 adaptive(自动选择)。带首帧图或首尾帧时建议填 adaptive,由首帧图决定比例;Seedance 2.5 这时只能填 adaptive,填其他比例时任务创建后会失败,冻结的余额全额退回。时长(秒),整数。Seedance 2.0 系列为 4–15,Seedance 2.5 为 4–30。填
-1 时由模型在可选范围内自动决定时长,实际时长见查询任务返回的 duration,并按实际时长计费。图片
填公网可访问的 https 图片链接,或图片的 Base64 编码(写法见下方「本机图片」)。| 项目 | 要求 |
|---|---|
| 格式 | jpeg、png、webp、bmp、tiff、gif、heic、heif |
| 大小 | 单张小于 30 MB;请求体不超过 64 MB,大文件请用链接,不要用 Base64 编码 |
| 宽高 | 每条边 300–6000 像素 |
| 宽高比(宽/高) | 0.4–2.5 |
| 数量 | 首帧 1 张;首尾帧 2 张;参考图:Seedance 2.0 系列 1–9 张,Seedance 2.5 为 1–30 张 |
- 含真人人脸的图片会被拒绝:返回 400
InputImageSensitiveContentDetected.PrivacyInformation,冻结的余额全额退回。 - 参考图可以填自己的素材 ID:
{"type": "image_url", "image_url": {"url": "asset://asset-xxx"}, "role": "reference_image"}。素材要先用素材管理接口创建,并等状态变成Active,写法见下方「更多示例」。 - 参考图数量超出上限时,任务创建后会失败,冻结的余额全额退回。
参考视频
填公网可访问的视频链接。不支持 Base64 编码(返回 400InvalidParameter)。
| 项目 | 要求 |
|---|---|
| 格式 | mp4、mov |
| 编码 | 视频 H.264、H.265;音频 AAC、MP3 |
| 数量和时长 | Seedance 2.0 系列:最多 3 个,单个 2–15 秒,合计不超过 15 秒。Seedance 2.5:最多 10 个,单个 2–30 秒,合计不超过 30 秒 |
| 大小 | 单个不超过 200 MB |
| 宽高 | 每条边 300–6000 像素,宽 × 高在 407696–8295044 之间 |
| 宽高比(宽/高) | 0.4–2.5 |
| 帧率 | 24–60 |
- 含真人人脸的视频会被拒绝。
- 在提示词里说明参考视频怎么用,写法见下方「更多示例」。
本机图片
把本机图片转换为 Base64 字符串,写成data:image/<图片格式>;base64,<Base64 编码> 填入 image_url.url,<图片格式> 用小写,如 data:image/png;base64,...。首帧、尾帧和参考图都可以这样传。不要填本机文件路径(如 /Users/...、file://...)。
首帧(命令行,把 first.png 换成你的图片):
IMAGE_BASE64=$(base64 < first.png | tr -d '\n')
cat > request.json <<JSON
{
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "一只手从枝头摘下沾着露水的红苹果,阳光透过树叶,镜头缓慢推近"},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,${IMAGE_BASE64}"}, "role": "first_frame"}
],
"resolution": "480p",
"ratio": "adaptive",
"duration": 5
}
JSON
curl --fail-with-body --silent --show-error \
--request POST \
--url https://code.heihuzi.ai/api/v3/contents/generations/tasks \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data @request.json
reference.jpg 换成你的图片):
import base64
import json
import os
import urllib.request
with open("reference.jpg", "rb") as f:
image_base64 = base64.b64encode(f.read()).decode()
body = {
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "参考图片1里的苹果饮品,杯子放在果园的木桌上,镜头缓慢环绕"},
{
"type": "image_url",
"image_url": {"url": f"data:image/jpeg;base64,{image_base64}"},
"role": "reference_image",
},
],
"resolution": "480p",
"ratio": "16:9",
"duration": 5,
}
request = urllib.request.Request(
"https://code.heihuzi.ai/api/v3/contents/generations/tasks",
data=json.dumps(body).encode(),
headers={
"Authorization": "Bearer " + os.environ["HEIHUZI_API_KEY"],
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request) as response:
print(response.read().decode())
响应
{"id":"cgt-20261005170037-c27t7"}
id 是任务号,用它查询和删除任务。
更多示例
文生视频(只传文字):{
"model": "doubao-seedance-2-5-260628",
"content": [{"type": "text", "text": "海浪轻轻拍打沙滩,夕阳映在水面上"}],
"resolution": "480p",
"ratio": "16:9",
"duration": 5
}
{
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "刚摘下的苹果变成一杯苹果饮品,镜头从果树拉远到果园"},
{"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"}, "role": "first_frame"},
{"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"}, "role": "last_frame"}
],
"resolution": "480p",
"ratio": "adaptive",
"duration": 5
}
{
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "参考视频1的运镜和节奏,把场景换成清晨的橘子果园,一只手摘下一个橘子"},
{"type": "video_url", "video_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"}, "role": "reference_video"}
],
"resolution": "480p",
"ratio": "16:9",
"duration": 5
}
{
"model": "doubao-seedance-2-0-mini-260615",
"content": [
{"type": "text", "text": "图片1的男子和图片2的女剑客并肩走在月下的古镇石板路上,镜头缓慢跟随"},
{"type": "image_url", "image_url": {"url": "asset://asset-20261101165247-rpf5s"}, "role": "reference_image"},
{"type": "image_url", "image_url": {"url": "asset://asset-20261101165309-6tc9s"}, "role": "reference_image"}
],
"resolution": "480p",
"ratio": "16:9",
"duration": 5,
"generate_audio": false
}
{
"model": "doubao-seedance-2-0-mini-260615",
"content": [
{"type": "text", "text": "参考视频1的运镜和节奏,图片1的柯基小狗在果园里跑向木桌,桌上放着图片2的苹果饮品"},
{"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_ref_2.png"}, "role": "reference_image"},
{"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"}, "role": "reference_image"},
{"type": "video_url", "video_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"}, "role": "reference_video"}
],
"resolution": "480p",
"ratio": "16:9",
"duration": 5
}
计费
- 按任务完成后返回的实际用量(
usage.completion_tokens)计费,不同模型、清晰度单价不同,价格以便利店当前分组配置和用量明细为准。 - 提交时按本次请求可能产生的最大用量冻结余额,生成成功后按实际用量扣费,多冻结的部分退回。
- 带参考视频时,参考视频的时长计入用量,并按含视频输入的单价计费。参考图不增加用量。
- 生成失败、超时、被取消,或请求被拒绝(例如图片含真人),冻结的余额全额退回。
限制
- 每个用户同时最多 5 个未完成的视频任务(排队中的也算,Seedance 和 MiniMax 的任务合计),超过返回 429
TooManyActiveTasks。 - 暂不支持:任务列表接口、联网搜索(
tools)。 - 素材 ID 请填在参考图(
"role": "reference_image")里,只能用自己账号下创建的素材;视频还没结束时,它引用的素材不能删除。 - 已不支持请求里的
portrait字段,会返回 400InvalidParameter;人物形象请改用素材 ID。
错误响应
错误的格式为{"error": {"code": "…", "message": "…", "param": "", "type": "…"}}。
| HTTP | error.code | 说明 |
|---|---|---|
| 400 | InvalidParameter | 参数不符合要求,例如 content 为空、base64 图片的内容不是图片、参考视频用了 base64、时长或画面比例超出该模型支持的范围 |
| 400 | PricingNotConfigured | 模型不支持这个清晰度,例如 mini 选 1080p |
| 400 | ToolNotAllowed | 使用了未开放的 tools |
| 400 | InputImageSensitiveContentDetected.PrivacyInformation | 图片可能含真人,审核未通过,冻结的余额已退回 |
| 402 | InsufficientBalance | 余额不足以冻结本次费用,返回里附 required_amount 和 available_amount |
| 403 | PermissionDenied | Key 没有绑定「Seedance 视频」分组 |
| 404 | model_not_found | 模型不在本站支持的列表里 |
| 404 | ResourceNotFound | 引用的素材 ID 不存在,或不是你自己的素材,本次未扣费 |
| 429 | TooManyActiveTasks | 未完成的任务太多,请等前面的完成后再提交 |
| 502 | UpstreamOutcomeUnknown | 提交结果暂时无法确认,不要立即重复提交;冻结保留,确认后自动结算或退回 |
| 503 | UpstreamUnreachable | 视频服务暂时连不上,本次未扣费,请稍后再试 |
| 503 | RefundPending | 视频服务连不上且退款还在核对中,不要立即重复提交,冻结的余额会由系统退回 |