ByteDance

Seedance 2.5

seedance-2.5/reference-to-video

字节 Seed 的音视频联合生成模型，支持最长 30 秒、最高 4K 的连续片段，并可基于多模态参考与时间戳级编辑精准控制画面

seedance-2.5/image-to-video seedance-2.5/reference-to-video seedance-2.5/text-to-video

试用 seedance-2.5/reference-to-video

输入

作品灵感

查看全部作品

输出

video

填写参数并生成，结果会显示在这里。

价格

seedance-2.5/reference-to-video 每秒

规格	单价
480P	$0.1215
720P	$0.2715
1080P	$0.680

定位简介

Seedance 2.5 的参考生视频线路，面向需要以素材约束画面一致性的视频生成任务。开发者提交提示词与至少一段参考视频，可同时附加图片与音频参考，让模型按 @image1、@video1、@audio1 的顺序引用素材，生成 4 至 30 秒、480p 到 1080p 的成片。适合广告、短剧与品牌内容团队在系列化创作中锁定角色、产品与场景外观，也适合需要同步音效与对白的叙事片段制作。

核心亮点

多模态素材共同约束画面——支持最多 30 张图片、10 段视频与 10 段音频同时作为参考，用于锁定产品、角色与场景外观。
提示词按序引用素材——在 prompt 中以 @image1、@video1、@audio1 的顺序指代参考项，把素材与画面目标明确对应。
时长与画幅可控——输出时长可选 4 至 30 秒或交由模型自动决定，画幅支持从 16:9、9:16 到 21:9 及跟随素材的自适应。
音画同步生成——默认生成与画面同步的对白、音效与背景音频，并可关闭以获得纯画面输出。

能力说明

参考视频驱动生成：输入至少一段参考视频，模型据此生成新片段而非延长或剪辑原片；适合需要复用既有镜头语言与画面质感的制作。

图片与视频混合参考：图片最多 30 张、视频最多 10 段，二者可组合提交，用来分别约束角色、产品与场景，降低系列内容的外观漂移。

音频参考与音频生成：可附加最多 10 段 wav 或 mp3 音频参考（需与至少一段参考视频同时提交），并选择是否生成同步对白、音效与背景声。

分辨率与输出格式选项：输出支持 480p、720p、1080p 三档，格式可选 mp4 或面向专业后期的 mov，按输出秒数计费。

联网检索补充信息：可开启 web_search，让模型在生成前检索提示词中涉及的时效性信息，适合需要引用当前事实的内容。

适用场景

广告与品牌团队做产品短片——以产品图片与实拍参考视频约束外观，生成 4 至 30 秒的广告片段，用于投放素材与社交媒体分发。
短剧团队维护角色一致性——用角色图片与既有片段作参考，批量生成同一角色的连续镜头，供分镜拼接待剪辑。
后期团队预演镜头方案——提交场景参考视频与构图图片，快速得到接近成片质感的预演片段，用于客户确认与拍摄前沟通。
内容团队做音画同步片段——提供配音或音乐参考并开启音频生成，产出带同步对白与音效的成片，直接用于成片或进一步混音。

限制与选型建议

单次生成片段最长 30 秒，更长的叙事需要拆分为多个片段分别生成再拼接。参考素材有明确约束：视频需 2 至 30 秒且总时长不超过 30 秒，音频总时长同样不超过 30 秒，单文件大小与像素数也有下限和上限，素材不合规会直接失败。本线路用于参考引导的生成，不支持视频剪辑或延长原片；多素材参考也意味着提示词编写与参数调试成本更高。轻量、单镜头且无一致性要求的需求，可考虑同系列文生视频线路。

常见问题

查看全部常见问题 →

Seedance 2.5 图生视频需要首帧和尾帧都上传吗？

不需要。首帧/首尾帧模式下，只上传 first_frame_url 时，模型会从首帧自然延展后续画面；需要控制镜头结束状态时，再同时提供 last_frame_url。尾帧不能单独使用。也可以改用 reference_image_urls 或 reference_audio_urls 作为参考模式，而不传端点帧。
首帧、首尾帧与多参考素材可以混在一次请求里吗？

当前 HiAPI Playground 将它们作为两种输入方式处理：首帧/首尾帧模式，或 reference_image_urls、reference_audio_urls 参考模式。为避免控制信号互相冲突，请每次保留一种方式；需要参考视频引导动作或运镜时，改用独立的 seedance-2.5/reference-to-video。
Seedance 2.5 图生视频支持哪些时长和分辨率？

当前请求契约支持 4–30 秒整数时长，以及 720p、1080p。输出 aspect_ratio 固定为 adaptive，会跟随首帧画幅。页面四个案例均为 720p，其中三个为 4 秒、一个为 5 秒；30 秒属于接口支持范围，页面暂无对应案例。
Seedance 2.5 图生视频如何计费？

按输出时长和分辨率计费，720p 与 1080p 使用不同的每秒档位；具体金额以模型页实时价格和任务记录为准。

提交生成任务

POST https://api.hiapi.ai/v1/tasks

请求头

Authorizationstring必填

账号 API Key，所有请求必填。示例：Bearer YOUR_HIAPI_API_KEY。获取 API Key

Content-Typestring可选

请求体固定按 JSON 解析；如携带，仅接受 application/json（可带 charset），其他取值返回 415。示例：application/json。

Idempotency-Keystring可选

幂等键，最长 255 字节。同账户同键的重试只创建一次任务，重放返回首次 taskId。

幂等键

网络超时或客户端自动重试时，同键只创建一次任务、不会重复扣费（幂等范围 = API Key 所属账户）。建议用业务侧唯一标识做键（如 "order-42"）；同键重放返回首次 taskId，键在首次提交 24 小时后过期。详细的场景矩阵见统一异步接口介绍页。

请求体

modelstring必填

当前固定值：seedance-2.5/reference-to-video

routestring可选

当前固定值：default

inputobject必填

seedance-2.5/reference-to-video 和线路 default 的业务参数对象，见下方参数表。

promptstring必填

生成指令，用于说明如何使用参考素材；按顺序以 @image1、@video1、@audio1 的形式引用参考项。该模型用于参考引导生成，不支持视频编辑或续写。

durationinteger可选默认值: 5

输出视频时长，单位为秒；可传 -1 表示自动时长，或传入 4 至 30 之间的整数。默认 5。

可选项：-145678910

显示全部（20 项）

1112131415161718192021222324252627282930

resolutionstring可选默认值: "480p"

输出视频分辨率，支持 480p、720p、1080p。默认 480p。

可选项：480p720p1080p

web_searchboolean可选默认值: false

是否允许模型联网搜索提示词中提到的实时信息。默认 false。

aspect_ratiostring可选默认值: "adaptive"

输出画面宽高比；adaptive 表示由模型跟随参考素材的比例。默认 adaptive。

可选项：16:94:31:13:49:1621:9adaptive

output_formatstring可选默认值: "mp4"

输出视频封装格式；mp4 为兼容性更好的默认格式，mov 面向专业后期制作。默认 mp4。

可选项：mp4mov

generate_audioboolean可选默认值: true

是否同步生成对白、音效与背景音频。默认 true。

reference_audio_urlsarray可选maxItems 10

参考音频 URL 数组，最多 10 段；每段须为 wav 或 mp3、大小不超过 15 MB、时长 2 至 30 秒，累计音频时长不得超过 30 秒。提供参考音频时须同时提供至少一个参考视频。

Array [ string ]

reference_image_urlsarray可选maxItems 30

参考图片 URL 数组，最多 30 张；支持 jpeg、png、webp、bmp、tiff、gif，单张不超过 30 MB，每边 300 至 6000 像素，宽高比 0.4 至 2.5，不支持 SVG、HEIC、HEIF。

Array [ string ]

reference_video_urlsarray必填minItems 1maxItems 10

参考视频 URL 数组，最多 10 段；每段须为 mp4 或 mov，总像素不低于 409600（如 854x480 及以上），帧率 24 至 60 fps，大小不超过 200 MB，时长 2 至 30 秒，每边 300 至 6000 像素，宽高比 0.4 至 2.5，累计视频时长不得超过 30 秒。

Array [ string ]

callbackobject可选

终态通知配置；为空则不回调，由调用方自行查询。详见下方回调说明。

回调（Webhook）

创建任务时提供 callback.url，任务终态时 HiAPI 主动 POST 通知你的服务，可免去轮询。回调请求体与任务详情数据结构同构；签名校验、投递重试与幂等说明见统一异步接口介绍页的回调说明。

urlstring必填

callback 存在时必填；任务终态后向该 URL 发起 POST，须为合法 http(s) URL。

whenstring可选默认值: "final"

当前仅支持 final，即 success / fail 均回调。

可选项：final

storagestring可选默认值: "temp"

产物存储档位：temp（默认，保留约 7 天）或 persistent（长期保存，按大小计费）。余额不足或超出存储上限会静默降级为 temp；实际生效档位见任务详情响应。

可选项：temppersistent

请求示例

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedance-2.5/reference-to-video",
  "input": {
    "prompt": "…",
    "duration": 5,
    "resolution": "480p",
    "web_search": false,
    "aspect_ratio": "adaptive",
    "output_format": "mp4",
    "generate_audio": true,
    "reference_video_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.5/reference-to-video",
    input: {
      "prompt": "…",
      "duration": 5,
      "resolution": "480p",
      "web_search": false,
      "aspect_ratio": "adaptive",
      "output_format": "mp4",
      "generate_audio": true,
      "reference_video_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "seedance-2.5/reference-to-video",
        "input": {
          "prompt": "…",
          "duration": 5,
          "resolution": "480p",
          "web_search": False,
          "aspect_ratio": "adaptive",
          "output_format": "mp4",
          "generate_audio": True,
          "reference_video_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

获取任务详情

GET https://api.hiapi.ai/v1/tasks/:id

响应字段

taskIdstring必填

任务 ID，前缀固定 tk-hiapi-。

modelstring必填

解析后的模型全名。用 route 参数提交的任务返回 base@线路（如 gpt-image-2/text-to-image@ext）；否则与创建时传入的模型名一致。

routestring可选

仅当任务用显式 route 参数提交时出现，回显提交时的原值。

statusstring必填

任务状态。

状态枚举

queued 已入队，尚未开始。 handling 处理中。 archiving 处理完成，产物准备中。 success 终态：完成，产物可用（返回 output）。 fail 终态：失败（返回 error）。提交后按 status 判断：success 或 fail 为终态，其余为非终态，建议按 1~3 秒间隔轮询直至终态。成功终态后从 output[].url 下载产物，并在 expireAt 前完成下载或转存；需要长期保留时在创建任务时使用 storage: "persistent"。

creatednumber必填

任务创建时间（Unix 秒）。

completednumber必填

进入终态的 Unix 秒；非终态固定为 0。

outputarray可选

仅 status == success 时出现。产物列表，始终为数组，同一任务可能同时返回多个 type（如 video + first_frame）。

Array [ object ]

数组元素

urlstring必填

资源 URL，可直接下载。

typestring必填

当前可能值：video、image、audio、first_frame、last_frame、thumbnail，后续可能会扩展。

expireAtnumber必填

资源可访问截止时间（Unix 秒）；过期前请完成下载或转存。

errorobject可选

仅 status == fail 时出现。

codestring必填

业务错误码。

messagestring必填

错误描述。

响应示例

成功

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

处理中（非终态）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

失败

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}