curl 示例。
变体
所有变体均为异步。通过
POST /api/v1/video/queue 提交,然后轮询 POST /api/v1/video/retrieve,直到响应体为 video/mp4。有关通用队列流程,请参阅视频生成。
resolution 传入以下值之一:480p、720p、1080p 或 4k(小写)。Seedance 2.0(非 Fast)接受全部四种;2.0 Fast 和 2.5 仅接受 480p / 720p。请使用 GET /models?type=video 查询实时的模型 ID 与能力 —— 不要在代码中硬编码可用性。
“一个模型,四种工作流”
参考生视频变体(seedance-2-0-reference-to-video-basic、其 Fast 兄弟以及 seedance-2-5-reference-to-video-basic)使用相同的提示词路由模式。模型会根据提示词前缀和输入的形式推断任务。 没有 task 或 workflow 字段 —— 提示词语法本身就是路由。
提示词语法是规范且区分大小写的:尖括号、首字母大写、数字前有一个空格 ——
<Video 1>、<Image 1>、<Audio 1>。
工作流模式
Reference 工作流
将上传的参考文件用作素材源 —— 主体、场景、运动、风格、人声音色 —— 从而生成一段全新的视频。 规范的提示词模式:Refer to <Subject 1> in <Image 1> to generate a 5-second clip of the same character riding a horse through snow.Refer to the camera scene in <Video 1> to generate a similar establishing shot of a futuristic city at dawn.Refer to <Subject 1> in <Image 1> and use the timbre in <Audio 1> for the narrator describing the scene.(音频素材必须至少与一个图像或视频参考搭配 —— 仅提交音频会被拒绝)
Edit 工作流
修改单个输入视频。任何未在提示词中明确点名的内容都会被保留。 当你想要局部改动(主体替换、天气 / 颜色变化、元素增删)而不是生成一段全新视频时,使用这个工作流。 规范的提示词模式:Strictly edit <Video 1>, changing its weather from sunny to a heavy rainstorm.Add snacks such as fried chicken and pizza to the countertop in <Video 1>.Remove the red car from <Video 1>, keeping the rest of the video content unchanged.Replace the perfume featured in <Video 1> with the face cream from <Image 1>, with all original motions and camera work preserved.
<Image 1> 作为替换内容的视觉素材源。
与源匹配的宽高比和时长
对于 Seedance 参考生视频的 edit / extend,你可以让输出跟随源片段,而不必固定选择某个比例或长度:
要求:
- Queue: 任何与源匹配的值都需要
reference_video_urls。 - Quote: 任何与源匹配的值都需要
reference_video_total_duration。与源匹配的时长按ceil(reference_video_total_duration)秒计费。 - 比例与时长相互独立 —— 你可以只匹配其中一项。
- 对于 extend,建议使用固定的
duration(决定生成时长),可选搭配aspect_ratio: "adaptive"。与源匹配的duration适用于 edit 风格的”与源等长”任务。
Extend 工作流
将单段视频在时间上向前或向后延伸。默认情况下 Seedance 只返回新生成的内容 —— 而不是把原始输入与延伸片段拼接后一起返回。这是为了保证转场连续性而设计的;如果你希望在延伸部分之外保留输入片段,请在提示词中明确说明:Extend <Video 1>, generate a dramatic chase scene through narrow alleys at dusk.Extend <Video 1> backward, the same character walking toward the camera before the original shot begins.Extend <Video 1>, start with <Video 1>, then the camera pulls back to reveal a vast landscape.
Stitch 工作流(轨道拼接)
用 AI 生成的转场把输入片段连接起来。请遵守多模态输入限制中家族特定的合并时长与片段数上限(Seedance 2.0:≤3 段 / 合计 ≤15 秒;Seedance 2.5:视频上限更高)。 规范的提示词模式:<Video 1> + a smooth seamless cut + followed by <Video 2><Video 1>. The moment a leaf falls to the ground, it sets off a special effect of golden particles. A gust of wind blows by, leading into <Video 2>.<Video 1> + a wisp of smoke transforms into a flock of birds + followed by <Video 2> + a slow dolly-in + followed by <Video 3>
通用提示词公式
在全部四个工作流中,推荐的编写公式是:- 主体 + 动作:逻辑基础 —— 定义”谁”在执行”什么动作”
- 环境 + 美学:空间背景、光照、视觉风格
- 摄像机:明确的镜头类型或运动
- 音频:环境音效或人声导引,让输出更具沉浸感
Strictly edit <Video 1>, changing its <subject + motion + environment + ...>),可以获得最高质量的输出。
多模态输入限制
下面列出的值是 Venice API 所接受的范围。超出这些范围的请求会在到达推理之前,被 schema 层以 400 拒绝。 Seedance 2.0 与 Seedance 2.5 使用不同的上限。 请始终查看你所调用的模型家族对应的列。各类媒体的共同下限
家族对比
参考音频仅在 R2V 变体上受支持。每个条目会作为
role: "reference_audio" 内容项转发给模型,并在提示词中以 <Audio 1>、<Audio 2> … 引用 —— 模型会根据提示词的表述方式,将每段音频用作人声音色、音效或背景音乐。旧版单数字段 audio_url 映射到相同的内容形态,现在等价于传入一个只有一个元素的 reference_audio_urls。
请求大小
队列端点接受的 JSON 请求体最大为 35 MB。较大的视频内联 data URL 有可能超过此限制 —— 对于多段拼接(Stitch)尤其如此,优先使用 URL 而非内联 base64。定价
在提交到/video/queue 之前,可以调用 POST /api/v1/video/quote 为给定的请求形态获取报价。报价端点是唯一权威来源;定价细节可能会变化,不应在客户端缓存或复制。
当请求中包含参考视频时,还需要传入 reference_video_total_duration(所有参考片段时长之和,单位为秒),以确保报价与 /video/queue 实际扣费一致:
完整示例
以下所有示例都假设VENICE_API_KEY 已在环境中设置。
文生视频
Seedance 2.0 文生视频(4K)
Seedance 2.5 文生视频(更长时长)
图生视频(首帧)
Seedance I2V 模型(
seedance-2-0-image-to-video-basic、其 Fast 变体,以及 seedance-2-5-image-to-video-basic)不接受 aspect_ratio —— 输出宽高比会根据输入图像的尺寸自动推导。传入该字段会返回 400 并附带消息 “This model does not support aspect_ratio”。如果你需要显式控制宽高比,请使用 T2V 或 R2V 变体。Reference 工作流 —— 主体素材源
Seedance 2.5 Reference 工作流 —— 多图像
Reference 工作流 —— 主体 + 音频素材源
Edit 工作流
Seedance 2.5 edit —— 与源匹配的时长和宽高比
duration: "auto"(或 "-1")和 aspect_ratio: "adaptive"(或 "auto")会让输出跟随源片段。参见与源匹配的宽高比和时长。
带图像基础的 Edit 工作流
向前延伸
拼接(3 段片段)
轮询直至完成
每次队列提交后,保存返回的queue_id,并轮询 /video/retrieve,直到响应体为 video/mp4:
{ "status": "queued" | "running" | "failed", ... });任务完成后,响应体切换为 video/mp4 字节。完整轮询模式请参阅视频生成。
故障排查
At least one reference is required for this model
参考生视频提交必须至少包含 reference_image_urls、reference_video_urls、image_references 或 video_references 之一。仅文本的生成不是有效的 R2V 工作流 —— 请改用文生视频的模型 ID。仅有 reference_audio_urls 也不够(参见上面的音频章节)。
参考视频 / 图像过多
Seedance 2.0 的 R2V 上限是 9 张图像和 3 段视频。Seedance 2.5 将上限提高到 30 张图像和 10 段视频。如果超过家族限制,请先在客户端裁剪输入或离线拼接。时长 / 合计时长错误
- 2.0: 每段参考视频/音频
[2, 15]秒;合计视频/音频 ≤ 15 秒;输出 4–15 秒。 - 2.5: 每段参考视频/音频
[2, 30]秒;合计视频/音频 ≤ 30 秒;输出 4–30 秒。 - 与源匹配的时长(Seedance 2.5 上的
-1/auto):源片段必须为 4–30 秒,且reference_video_urls(queue)或reference_video_total_duration(quote)为必填。
提示词被路由到了错误的工作流
工作流由提示词语法推断。常见的误路由情形:- 想要 Extend,但写成了
Refer to ...→ 模型会把你的视频当作素材源,而不是要延续的画布 - 想要 Stitch,但写成了
Refer to ...→ 模型会选其中一段作为素材源,忽略其他 - 想要 Edit,但写成了
Generate a video based on <Video 1>→ 语义不明;模型可能默认走 Reference
Strictly edit <Video 1>, ...、Extend <Video 1>, ...、<Video 1> + ... + followed by <Video 2>。
不支持的包含人物的媒体
公共 Seedance API 模型不运行同意声明流程(consents.seedance / needs_consent)。包含可检测人物的媒体可能因内容政策或提供方错误而失败。请改用 Venice 应用或 Studio。
报价与队列扣费不一致
如果请求包含参考视频,但你没有向/video/quote 传入 reference_video_total_duration,报价与队列扣费可能会不一致。当请求中存在参考视频时,请始终传入 reference_video_total_duration(所有参考片段时长之和,单位为秒)。
参考资料
- Venice 视频队列端点:
POST /api/v1/video/queue - Venice 报价端点:
POST /api/v1/video/quote - 配套指南:参考生视频(涵盖 Kling O3 + Grok Imagine R2V)
- 配套指南:视频生成(队列 / 轮询概览)