AI 视频生成 API 接口文档

概述

基于火山引擎 Seedance 2.0 模型的 AI 视频生成服务。支持文本生成视频、图片参考生成视频、多模态参考生成视频。

Base URL: https://ai.wisech.com

鉴权: 所有请求需在 Header 中携带 API Key

Authorization: Bearer sk-你的密钥

一、创建视频生成任务

请求

POST https://ai.wisech.com/v1/videos
Content-Type: multipart/form-data

参数

参数	类型	必填	说明
model	string	是	模型名称（见「可用模型」）
prompt	string	是	文本提示词，描述你想生成的视频内容
metadata	string	是	JSON 字符串，包含参考素材和生成参数

metadata JSON 结构

{
    "content": [],
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
}

字段	类型	必填	默认值	说明
content	array	否	[]	参考素材列表（图片/视频/音频），不传则为纯文生视频
generate_audio	boolean	否	true	是否生成同步音频（人声+音效+背景音乐）
ratio	string	否	16:9	视频宽高比：`16:9` `4:3` `1:1` `3:4` `9:16` `21:9`
duration	integer	否	5	视频时长，单位：秒，范围 4-15
watermark	boolean	否	false	是否添加 AI 生成水印

content 数组 — 参考素材

每个元素代表一个参考素材。支持图片、视频、音频三种类型。

参考图片

{
    "type": "image_url",
    "image_url": {
        "url": "https://你的图片地址.jpg"
    },
    "role": "reference_image"
}

字段	说明
type	固定 `image_url`
image_url.url	图片的公网 URL 地址
role	图片用途（见下方 role 说明）

图片要求：

格式：jpeg、png、webp、bmp、tiff、gif、heic、heif

宽高比：0.4 ~ 2.5

宽高像素：300 ~ 6000 px

大小：单张 < 30 MB

数量：最多 9 张

参考视频

{
    "type": "video_url",
    "video_url": {
        "url": "https://你的视频地址.mp4"
    },
    "role": "reference_video"
}

视频要求：

格式：mp4、mov

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

时长：2-15 秒（所有视频总时长 ≤ 15秒）

大小：单个 < 50 MB

数量：最多 3 个

参考音频

{
    "type": "audio_url",
    "audio_url": {
        "url": "https://你的音频地址.mp3"
    },
    "role": "reference_audio"
}

音频要求：

格式：wav、mp3

时长：2-15 秒（所有音频总时长 ≤ 15秒）

大小：单个 < 15 MB

数量：最多 3 段

注意：不可单独传音频，需至少包含 1 个参考图片或视频。

role 说明（重要）

role 值	适用类型	说明
`reference_image`	图片	普通参考图片
`reference_role`	图片	人物角色参考图（含人脸的虚拟人像）
`reference_video`	视频	参考视频
`reference_audio`	音频	参考音频

reference_role 和 reference_image 的区别：
reference_image：场景、物体、构图等普通参考图
reference_role：包含人脸的角色图（虚拟人像），系统会自动处理人脸素材以确保合规生成

提示词中引用素材

在 prompt 中用 「图片1」「图片2」「视频1」「音频1」 的方式引用素材。序号为该类型素材在 content 数组中的出现顺序。

例如 content 中有 3 张图片和 1 段音频：

prompt: "图片1中的女孩穿着图片2中的衣服，在图片3的场景中跳舞，全程使用音频1作为背景音乐"

完整请求示例

成功响应

{
    "id": "task_t5NYGw2ZdcdFezqReYKLnffs69L5cvIB",
    "task_id": "task_t5NYGw2ZdcdFezqReYKLnffs69L5cvIB",
    "object": "video",
    "model": "doubao-seedance-2-0-260128-720p",
    "status": "queued",
    "progress": 0,
    "created_at": 1780993162
}

字段	说明
id / task_id	任务 ID，用于查询进度
status	初始状态为 `queued`（排队中）
created_at	创建时间（Unix 时间戳）

二、查询视频生成任务

请求

GET https://ai.wisech.com/v1/videos/{task_id}

参数

参数	位置	说明
task_id	URL 路径	创建任务时返回的 id

请求示例

响应示例

排队中 / 生成中：

{
    "id": "task_t5NYGw2ZdcdFezqReYKLnffs69L5cvIB",
    "task_id": "task_t5NYGw2ZdcdFezqReYKLnffs69L5cvIB",
    "object": "video",
    "model": "doubao-seedance-2-0-260128-720p",
    "status": "in_progress",
    "progress": 50,
    "created_at": 1780993162
}

生成成功：

{
    "id": "task_t5NYGw2ZdcdFezqReYKLnffs69L5cvIB",
    "task_id": "task_t5NYGw2ZdcdFezqReYKLnffs69L5cvIB",
    "object": "video",
    "model": "doubao-seedance-2-0-260128-720p",
    "status": "succeeded",
    "progress": 100,
    "created_at": 1780993162,
    "completed_at": 1780993452,
    "result_url": "https://xxx.volcvideo.com/xxxx.mp4?auth_key=...",
    "usage": {
        "completion_tokens": 86955,
        "total_tokens": 86955
    }
}

生成失败：

{
    "id": "task_t5NYGw2ZdcdFezqReYKLnffs69L5cvIB",
    "task_id": "task_t5NYGw2ZdcdFezqReYKLnffs69L5cvIB",
    "object": "video",
    "model": "doubao-seedance-2-0-260128-720p",
    "status": "failed",
    "progress": 100,
    "error": {
        "code": "generation_failed",
        "message": "视频生成失败"
    }
}

任务状态

status	说明	建议操作
queued	排队中	继续轮询
in_progress	生成中	继续轮询
succeeded	生成成功	取 result_url 下载视频
failed	生成失败	查看 error 信息

轮询建议

建议轮询间隔：5-10 秒

视频生成通常需要 30秒 ~ 3分钟（取决于时长和分辨率）

视频 URL 有效期 24 小时，请及时下载或转存

三、可用模型

模型名称	说明	分辨率	生成速度
doubao-seedance-2-0-260128-480p	Seedance 2.0 标准版	480p	标准
doubao-seedance-2-0-260128-720p	Seedance 2.0 标准版	720p	标准
doubao-seedance-2-0-260128-1080p	Seedance 2.0 标准版	1080p	标准
doubao-seedance-2-0-fast-260128-480p	Seedance 2.0 极速版	480p	更快
doubao-seedance-2-0-fast-260128-720p	Seedance 2.0 极速版	720p	更快
doubao-seedance-2-0-fast-260128-1080p	Seedance 2.0 极速版	1080p	更快

标准版画质更高，极速版生成更快。分辨率越高，消耗额度越多。

四、使用场景示例

纯文生视频（无参考素材）

单图生视频（首帧参考）

多角色人物视频

带参考视频+音频

五、错误码

HTTP 状态码	说明
200	成功
400	请求参数错误
401	认证失败（Key 无效/过期/余额不足）
404	任务不存在
429	请求频率超限
500	服务内部错误

六、常见问题

Q：视频生成要多久？
A：通常 30 秒 ~ 3 分钟，取决于时长、分辨率和是否有参考素材。

Q：reference_role 和 reference_image 该怎么选？
A：图片里有明确的人脸/人物角色用 reference_role，其他所有情况用 reference_image。

Q：可以同时传多少张图片？
A：最多 9 张参考图片 + 3 个参考视频 + 3 段参考音频。

Q：视频 URL 能用多久？
A：24 小时，请及时下载或转存到自己的存储。

Q：如何获取 API Key？
A：联系管理员开通账户并获取密钥。

概述#

一、创建视频生成任务#

请求#

参数#

metadata JSON 结构#

content 数组 — 参考素材#

参考图片#

参考视频#

参考音频#

role 说明（重要）#

提示词中引用素材#

完整请求示例#

成功响应#

二、查询视频生成任务#

请求#

参数#

请求示例#

响应示例#

任务状态#

轮询建议#

三、可用模型#

四、使用场景示例#

纯文生视频（无参考素材）#

单图生视频（首帧参考）#

多角色人物视频#

带参考视频+音频#

五、错误码#

六、常见问题#

概述