Docs / 视频生成

视频生成

RelayDance 以异步方式生成视频: 你先提交任务，然后轮询直到任务完成，或者设置 webhook 回调，完全无需轮询。两次 HTTP 调用（使用 webhook 时只需一次）即可从提示词得到最终的 mp4。

#任务流程

提交: POST /v1/video/generations 会立即返回 { "task_id": "...", "status": "submitted" }。
轮询: 调用 GET /v1/video/generations/{task_id}，直到 status 变为 succeeded（url 字段即为生成的片段）或 failed。
或使用 webhook: 在提交时设置 metadata.callback_url，任务完成时最终任务状态会以 POST 方式推送到你的 URL。

#提交任务

terminalbash

curl https://relaydance.com/v1/video/generations \
  -H "Authorization: Bearer $RELAYDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-1080p",
    "prompt": "A dancer spins in golden hour light, cinematic",
    "seconds": "10",
    "metadata": {
      "ratio": "16:9",
      "resolution": "1080p",
      "generate_audio": true,
      "callback_url": "https://your-server.example.com/webhook"
    }
  }'

response.jsonjson

{
  "task_id": "task_abc123",
  "status": "submitted"
}

请求参数

参数	类型	说明
`model`	string	视频模型 ID（见下方列表）
`prompt`	string	片段的文字描述。使用参考图时，用 @image1 到 @imageN 来引用它们
`seconds`	string	片段时长（秒），以字符串形式传入（如 "5"、"10"）; 最大值取决于模型
`metadata`	object	厂商参数: 所有模型专属的参数都放在这里

metadata 字段

字段	类型	说明
`ratio`	string	宽高比，如 "16:9"、"9:16"、"1:1"
`resolution`	string	"480p" \| "720p" \| "1080p"（取决于模型）
`generate_audio`	boolean	生成配乐（Seedance 2.0 系列模型支持）
`callback_url`	string	Webhook URL: 任务完成时最终任务状态会以 POST 推送到此处
`content`	array	参考媒体条目（图像、视频、音频），见下文

callback_url 始终放在 metadata 内部，绝不能放在请求体的顶层。

#轮询任务

terminalbash

curl https://relaydance.com/v1/video/generations/task_abc123 \
  -H "Authorization: Bearer $RELAYDANCE_API_KEY"

response.jsonjson

{
  "task_id": "task_abc123",
  "status": "succeeded",
  "url": "https://...mp4",
  "format": "mp4",
  "metadata": { "ratio": "16:9", "resolution": "1080p" }
}

状态	含义
`submitted`	任务已接受并进入队列
`running`	正在生成中
`succeeded`	已完成: 从 url 字段下载片段
`failed`	生成失败; 失败的任务不计费

#Webhook 回调

如果你在提交时设置了 metadata.callback_url，就无需轮询: 当任务到达最终状态时，RelayDance 会把上面所示的同一份任务 JSON 以 POST 推送到你的 URL，投递失败时会重试。

Webhook 是生产环境的推荐方式: 无需轮询循环，不浪费请求，片段就绪的那一刻你的服务器就能立即响应。

#参考媒体与 @imageN

参考媒体用于引导生成: 保持产品外观一致、复用某个角色、匹配某段动作或配乐。请在 metadata.content[] 中传入这些条目:

content.jsonjson

{
  "model": "seedance-1-5-pro-with-audio",
  "prompt": "@image1 slowly turns its head toward the camera, soft studio light",
  "seconds": "5",
  "metadata": {
    "ratio": "16:9",
    "resolution": "720p",
    "content": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/cat.jpg" },
        "role": "reference_image"
      }
    ]
  }
}

type	载荷字段	role	上限
`image_url`	image_url.url	reference_image	每次请求最多 9 张图片
`video_url`	video_url.url	reference_video	每次请求最多 3 个视频
`audio_url`	audio_url.url	reference_audio	每次请求最多 3 条音轨

在提示词中，按参考图在 content[] 中的顺序用 @image1 到 @imageN 引用它们: @image1 是第一条，@image2 是第二条，依此类推。

参考图与首尾帧模式互斥: 单次请求只能使用其中一种。本地文件可以先通过上传文件托管。

#视频模型

模型 ID	系列	说明
doubao-seedance-2-0-1080p	Seedance 2.0	旗舰画质，1080p 输出
doubao-seedance-2-0-720p	Seedance 2.0	720p 输出
doubao-seedance-2-0-fast-260128	Seedance 2.0	生成更快
seedance-1-5-pro-with-audio	Seedance 1.5	含生成音频
seedance-1-5-pro-no-audio	Seedance 1.5	无声输出
happyhorse-1.0-t2v	HappyHorse	文生视频
happyhorse-1.0-i2v	HappyHorse	图生视频
happyhorse-1.0-r2v	HappyHorse	参考图生视频
happyhorse-1.0-video-edit	HappyHorse	视频编辑

Seedance 2.0 涵盖 480p、720p、1080p 和原生 4K，另有 Fast 与 Mini 变体。支持的时长、宽高比和分辨率因模型而异; 各模型的详情与价格请参见模型页面。

任务立即开始且无排队，无需 BytePlus 账户或 KYC，并支持人脸与人像生成。RelayDance 还提供官方平台没有的特殊 SKU。失败的请求不计费。

#后续步骤

图生视频示例 : 用参考媒体让静态图像动起来
上传文件 : 托管本地图像以用作参考
生成视频接口文档 : 完整的请求与响应结构
获取视频任务接口文档 : 轮询端点与状态枚举

←概览图像生成→