视频生成:从文字与素材到成片
视频生成是异步任务:先提交拿到 task_id, 再轮询取片,通常 2~5 分钟完成。支持文生视频、首帧/首尾帧图生视频、参考图/参考视频/参考音频的多模态素材组合, 海外版模型另支持 4K 输出。本页所有参数与用量数字均经真实出片逐项验证。 两条产品线同一接口:Seedance(字节,按 tokens 计费)与 万相 3.0(阿里,按秒计费,见页中「万相 3.0」节)。
快速上手(提交 + 轮询两段式)
网关地址 https://gw.aiapiway.com/v1,密钥须选对应视频分组(2.0 用「视频 · 标准」,2.5 用「Seedance 2.5 · 标准」)。最关键的一条:时长、分辨率等参数一律放 metadata 里—— 写在顶层会被静默忽略、按默认 5 秒 / 720p 出片。
import requests, time
BASE = "https://gw.aiapiway.com/v1"
H = {"Authorization": "Bearer sk-aiapiway-****", "Content-Type": "application/json"}
# ① 提交任务(文生视频)
task = requests.post(f"{BASE}/video/generations", headers=H, json={
"model": "doubao-seedance-2-0-260128",
"prompt": "一只猫在草地上奔跑,阳光明媚",
"metadata": { # ⚠️ 参数必须放 metadata 里,顶层会被忽略
"resolution": "720p", # 480p / 720p / 1080p(4K 见海外版模型)
"duration": 5, # 秒,Seedance 2.0 最长 15
"generate_audio": False, # 默认 true(同步音频);不需要时建议显式关闭
},
}).json()
task_id = task["task_id"]
# ② 轮询结果(通常 2~5 分钟出片;失败自动全额退款)
while True:
time.sleep(10)
r = requests.get(f"{BASE}/video/generations/{task_id}", headers=H).json()["data"]
if r["status"] == "SUCCESS":
print("视频地址(24 小时内有效,请及时转存):", r["result_url"]); break
if r["status"] == "FAILURE":
print("失败(预扣已自动退回):", r["fail_reason"]); break轮询返回 data.status:QUEUED → IN_PROGRESS → SUCCESS / FAILURE; 成功时 data.result_url 即视频直链(约 24 小时有效,请及时转存); 失败时预扣费用自动全额退回,不收一分钱。
传素材:首尾帧、参考图 / 视频 / 音频
素材经 metadata.content 数组传递,每个素材项用 role 声明用途;图片既可用公网 URL,也可用 data:image/jpeg;base64,... 直接内嵌(私有素材不必先找图床):
{
"model": "doubao-seedance-2-0-260128",
"prompt": "镜头从白天草地过渡到黄昏,太阳缓缓落下",
"metadata": {
"resolution": "720p",
"duration": 5,
"content": [
{ "type": "image_url", "role": "first_frame",
"image_url": { "url": "https://example.com/day.jpg" } },
{ "type": "image_url", "role": "last_frame",
"image_url": { "url": "data:image/jpeg;base64,..." } }
]
}
}first_frameimage_url首帧图:视频从这张图开始(经典图生视频)。last_frameimage_url尾帧图:视频收在这张图;与 first_frame 同传即「首尾帧」过渡生成。reference_imageimage_url参考图:借用其风格/色调/主体,可传多张。reference_videovideo_url参考视频:借用其场景与运镜(视频输入的 tokens 会计入用量,单价档更低,见计费)。reference_audioaudio_url参考音频:控制节奏/配音参考。⚠️ 不能作为唯一素材,必须搭配图或视频参考一起传。素材项可以自由组合(如 首帧 + 参考音频、参考图 × 2 + 参考视频);提示词永远走顶层 prompt。输入的图片/音频不额外计费,输入视频的 tokens 计入用量(但按更低的「含视频输入」单价档结算,见下节)。
参数参考
prompt(顶层)文本提示词,必填。想传多段文本也可以,但最终以顶层 prompt 为准(metadata.content 里的 text 项会被网关用 prompt 替换)。metadata.resolution输出分辨率:480p / 720p(默认) / 1080p;4K 仅海外版模型支持(填 "4k")。metadata.duration时长(秒,数字),Seedance 2.0 最长 15,不传默认 5。⚠️ 写在顶层的 duration 会被静默忽略。metadata.ratio画幅比例,如 "16:9"(默认)、"9:16"、"1:1"、"4:3"。metadata.generate_audio是否生成同步音频,默认 true。不需要音频时建议显式传 false——可避开偶发的「输出音频版权检测」误伤(见下方常见失败)。音频不额外计费。metadata.watermark是否叠加「AI生成」水印角标,默认 false。metadata.seed / camera_fixed随机种子(复现用)/ 固定机位(布尔)。metadata.content素材数组(v3 能力):每项 type 为 image_url / video_url / audio_url,配 role 声明用途,详见下节。images(顶层数组)简化写法:只传图片 URL 数组、不带 role(等价于普通图生视频参考)。要精确控制首帧/尾帧请改用 metadata.content。duration / resolution(顶层)⚠️ 陷阱:顶层的这两个字段网关不透传,会按默认值(5 秒 / 720p)出片并按实际出片计费。参数一律放 metadata 内。人物素材库(Seedance 2.0 / 2.5)
需要成片里保持同一张人物脸时,先把公网图片登记成素材,再在视频请求里引用返回的 asset://。 登记接口在本站 POST /api/v1/video/assets, 用对应型号的视频密钥(2.0 用「视频 · 标准」;2.5 用「Seedance 2.5 · 标准」)。image_url 必须是上游能直接下载的 https 图片文件,不要传网页地址。 请用虚拟人物;真人照片不保证通过。2.0 与 2.5 共用同一素材池,登记一次即可在对应型号出片时引用。
# ① 登记素材(本站接口;2.0 用「视频 · 标准」、2.5 用「Seedance 2.5 · 标准」;必须是 https 文件)
# 人物图:
curl https://aiapiway.com/api/v1/video/assets \
-H "Authorization: Bearer $AIAPIWAY_KEY" -H "Content-Type: application/json" \
-d '{"image_url":"https://example.com/character.jpg","name":"角色甲"}'
# 参考视频(续段):改用 "video_url":"https://example.com/clip.mp4"
# 返回 asset_url,形如 asset://as_xxxxxxxx;勿贴火山控制台 Asset ID / 旧 asset://asset-…
# 同一素材池:2.0 / 2.5 登记一次即可,出片时 model 换成对应型号
# ② 出片时把 asset_url 放进 reference_image;提示词用「图片1」
# 2.5 把 model 换成 doubao-seedance-2-5 即可
curl https://gw.aiapiway.com/v1/video/generations \
-H "Authorization: Bearer $AIAPIWAY_KEY" -H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0-260128",
"prompt": "图片1中的人物轻微转头看向镜头,保持服装,自然光,电影感",
"metadata": {
"resolution": "720p",
"duration": 4,
"ratio": "16:9",
"generate_audio": false,
"content": [
{
"type": "image_url",
"role": "reference_image",
"image_url": { "url": "asset://as_xxxxxxxx" }
}
]
}
}'查询 GET /api/v1/video/assets/{id}, 删除用同一地址的 DELETE。只能看到自己密钥登记过的素材。 登记不另收费;出片仍按型号、时长、分辨率计费。
选哪个模型?国内版 vs 海外版
doubao-seedance-2-0-260128(2.0 国内版):日常首选, 480p/720p/1080p 全档可用,素材能力齐全;不支持 4K。请用密钥分组「视频 · 标准」。 固定人物脸见上方「人物素材库」节。
doubao-seedance-2-5(2.5):新一代视频生成, 调用方式与 2.0 相同(参数放 metadata)。请用密钥分组「Seedance 2.5 · 标准」,不能用 2.0 那把视频钥匙。含人脸时同样走上方「人物素材库」登记asset://(与 2.0 共用素材池)。
doubao-seedance-2-0-filter-off(海外版):唯一的 4K 通道(resolution 填 "4k",实测输出 3840×2160), 创作自由度更高;4K 用量大(见下表),请确保余额充足。
万相 3.0(阿里百炼直连,按秒计费)
wan3.0-video(标准版)与 wan3.0-video-prime(优速版:能力相同、出片更快、单价为标准版 1.5 倍), 用「视频 · 标准」那把钥匙即可,与 Seedance 2.0 同组、不用换钥匙。接口、提交 / 轮询两步、task_id / result_url 的拿法与上文完全一致, 只是 metadata 口径不同:分辨率写大写、时长 2–30 秒或 -1、比例多了 adaptive, 素材多了文档 / 网页生视频。统一视频模型,一个型号覆盖文生、首尾帧、参考图 / 视频 / 音频、编辑延长全部场景。
{
"model": "wan3.0-video",
"prompt": "一只猫在草地上奔跑,阳光明媚,写实风格",
"metadata": {
"resolution": "720P", // 480P / 720P(默认) / 1080P;按秒计费 1 : 2 : 4
"duration": 5, // 2–30 的整数;-1 = 智能时长(先按 30 秒预扣,出片后按真实秒数退差)
"ratio": "16:9", // adaptive(默认)/ 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16;不传由模型自适应
"audio": true, // 同步音频,默认开;关掉不省钱(generate_audio 是同义别名)
"prompt_extend": true // 提示词智能改写,默认开;含 file / link 时必须开
}
}metadata.resolution480P / 720P(默认)/ 1080P,大写(小写也认)。按秒计费,三档单价 1 : 2 : 4;1080P 要显式声明。metadata.duration2–30 的整数秒;或 -1 = 智能时长(模型按内容定长,先按 30 秒预扣、出片后按真实秒数退差)。⚠️ -1 只能放 metadata,写顶层会被通用校验拒掉。metadata.ratioadaptive(默认,按素材自适应)/ 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16;不传不发给上游,由模型自适应。metadata.audio同步音频,默认 true;generate_audio 是同义别名(两者同传以 audio 为准)。关掉不省钱。metadata.prompt_extend提示词智能改写,默认 true;带 file / link 素材时必须为 true(传 false 会 400)。metadata.seed / watermark随机种子(-1 或 0–2147483647)/ 「AI生成」水印角标(默认 false)。metadata.content统一素材协议,与 Seedance 同形;role 多了 file / link(文档 / 网页生视频),组合规则见下。不支持的字段negative_prompt / template / driving_audio → 直接 400(万相 3 没有这些能力);camera_fixed / return_last_frame / callback_url / tools 等 Seedance 独有字段会被忽略。素材怎么组合(违反会直接 400,不会先扣费)
计费是按秒不是按 tokens:单价 = 480P 每秒基准价 × 分辨率系数(480P ×1 / 720P ×2 / 1080P ×4)× 秒数, 音频开关不影响价格;提交时按请求秒数精确预扣(智能时长 -1 先按 30 秒预扣),出片后按真实秒数多退少补,失败全额退回。 两款型号的每秒基准价见模型与价格(展示单位「/秒 · 480P」)。 通常 1~3 分钟出片;成片直链同样约 24 小时有效,请及时转存。
计费(Seedance):先预扣、出片后按实际用量多退少补
提交时先冻结一笔预估费用(余额不足会直接拒单),出片后按上游返回的实际 tokens 结算、 多退少补——账单明细里会分别标出「预扣 / 补扣 / 退款」,合计才是该次实付。任务失败则预扣全额退回。 tokens 与像素面积、时长近似线性,实测参考(5 秒、16:9):
tokens / 5 秒50,638规律≈ 10,000 tokens/秒tokens / 5 秒108,900规律21,600 tokens/秒 + 900tokens / 5 秒245,025规律单价另有 1080p 档系数tokens / 5 秒980,100规律像素面积为 720p 的 9 倍,tokens 同比 9 倍含参考视频输入时,输入视频的 tokens 计入总量(约等于同规格输出的量), 但整单按更低的「含视频输入」单价档结算,平台已自动套用,无需任何设置。 价格对标官方平台价,各模型单价见模型与价格。
常见失败与对策
生成了 5 秒 / 720p 的片子,和我要的参数不一样?›
十有八九是把 duration / resolution 写在了请求顶层——顶层参数不透传,会按默认值出片并按实际出片计费。全部改放 metadata 内即可(见参数参考表)。
失败提示 OutputAudioSensitiveContentDetected(输出音频版权检测)?›
同步音频默认开启,偶发会被上游的音频版权检测误伤(即使提示词完全无害)。费用已自动全额退回;不需要音频时显式传 metadata.generate_audio: false 可彻底避开,需要音频则直接重试一次即可。
传了素材却报 InvalidParameter?›
常见三种:① reference_audio 不能是唯一素材,须搭配图或视频;② 素材 URL 必须公网可达(或改用 base64 data URL);③ 该分辨率/时长组合模型不支持(如国内版传 4k、duration 超 15)。报错信息里带上游原文,照着改即可。
4K 任务提交被拒:预扣费额度失败?›
4K 的 tokens 是 720p 的 9 倍,请确保余额足够(参考模型与价格页按 980,100 tokens/5 秒估算),或先用 720p 验证创意再出 4K 成片。
万相 3 提交就 400:first_frame/last_frame cannot be combined… / negative_prompt / duration?›
万相 3 的校验在网关侧先做、不打上游也不扣费:① 首帧 / 首尾帧不能与参考图 / 参考视频 / 参考音频 / file / link 同传,拆成两次任务;② negative_prompt、template、driving_audio 万相 3 不支持,删掉(反向需求写进 prompt,参考音频用 role reference_audio);③ duration 只能是 2–30 的整数或 -1,且 -1 必须放 metadata;④ file / link 场景 prompt_extend 不能关。报错原文就是违反的那条规则。
万相 3 智能时长(-1)为什么先扣了 30 秒的钱?›
智能时长由模型按内容定长(2–30 秒),提交时无法预知,所以先按上限 30 秒预扣;出片后按真实秒数立即退差,账单里会看到一笔「预扣」和一笔「退款」。想精确控制花费就直接填整数秒。