API-RUN

简体中文

English

简体中文

English

Appearance

Seedance 官方一致接入（生成视频） ​

API-RUN 提供 Seedance 2.0 / 2.5 系列视频生成能力：接口与火山方舟官方文档一致——请求报文、路径、任务 ID（cgt- 原生 ID）、官方 Model ID、官方刊例计费全部同源，照官方文档写、仅改 base_url 与密钥即可接入。

素材库与真人认证是独立文档：Seedance 素材库/真人认证。

端点 ​

  • 创建任务：POST $URL/api/v3/contents/generations/tasks
  • 查询任务：GET $URL/api/v3/contents/generations/tasks/{task_id}
  • 任务列表：GET $URL/api/v3/contents/generations/tasks
  • 取消任务：DELETE $URL/api/v3/contents/generations/tasks/{task_id}
  • 统一入口（OpenAI Video 风格）：POST $URL/v1/videos，查询 GET $URL/v1/videos/{task_id}

任务路径与火山方舟官方文档一致；/v3/video/tasks（含 /{task_id}、列表、取消）为等价路径，同样可用——三套路径同源同协议，客户从任一入口迁移均零成本。任务不存在时统一返回 404（error.code=task_not_exist）。

任务接口使用 Bearer 鉴权：

http
Authorization: Bearer $YOUR_API_KEY

支持模型（官方 Model ID） ​

平台统一使用厂商官方 Model ID（国际版官方发布名），报文协议完全一致。

模型定位分辨率时长
dreamina-seedance-2-5-2606282.5 旗舰版，质量与一致性最强480p / 720p / 1080p4–30 秒
dreamina-seedance-2-0-2601282.0 标准版480p–4k4–15 秒
dreamina-seedance-2-0-fast-2601282.0 快速版480p / 720p4–15 秒
dreamina-seedance-2-0-mini-2606152.0 轻量版480p / 720p4–15 秒

duration 另支持 -1（智能时长，由模型自定）。fast/mini 不支持 1080p 与 4k；2.5 的 1080p 档计费单列（见价格表）。

计费说明 ​

按官方 token 口径计费：tokens = (输入视频时长 + 输出时长) × 输出分辨率像素 × 帧率 / 1024，提交时按预估预扣，任务完成后按实际 token 用量差额结算（多退少补）。带视频参考的任务按「视频参考」档单价（该档更便宜）。

模型视频参考（USD / 百万 token）无视频参考（USD / 百万 token）
dreamina-seedance-2-5-2606286.4（1080p 7.0）10.7（1080p 11.7）
dreamina-seedance-2-0-2601284.3（1080p 4.7、4k 2.4）7.0（1080p 7.7、4k 4.0）
dreamina-seedance-2-0-fast-2601283.35.6
dreamina-seedance-2-0-mini-2606152.13.5

创建任务参数 ​

content 与 prompt 至少提供一项：content 里没有非空文本项时，prompt 会作为一条 text 项加入。

字段类型必填说明
modelstring是上表中的模型名
contentarray否多模态内容数组，元素为 {type, text?, image_url?, video_url?, audio_url?, draft_task?, role?}，type 取 text / image_url / video_url / audio_url / draft_task
promptstring否文本提示词（content 无非空文本项时作为 text 项加入）
callback_urlstring否任务完成回调地址
return_last_frameboolean否是否返回尾帧图片
service_tierstring否服务层级：default / flex
execution_expires_afterinteger否执行过期时间（秒）
generate_audioboolean否是否生成音频，默认 true
draftboolean否是否草稿模式（样片两步流，见下）
toolsarray否工具列表（任务响应可返回 web_search 的 tool_usage）
safety_identifierstring否安全标识
priorityinteger否优先级
resolutionstring否480p / 720p / 1080p / 4k，默认 720p
ratiostring否16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / adaptive，默认 16:9；adaptive 按输入图片自适应宽高比
durationinteger否视频时长（秒）：2.5 支持 4–30，2.0 系列 4–15，另支持 -1（智能时长）；默认 5
framesinteger否帧数
seedinteger否随机种子
camera_fixedboolean否镜头锁定
watermarkboolean否是否加水印
bitrate_modestring否码率模式
omni_reference_task_typestring否全参考任务类型
output_formatstring否输出格式

content 合法组合 ​

content 内文本提示词可选——与火山方舟官方一致，支持：纯文本；文本（可选）+ 图片 / 视频 / 音频的任意组合；样片任务引用（draft_task，仅 2.5）。不填文本、仅传图片 / 视频 / 音频 / 样片引用均合法；content 为空数组或缺失才会被拒绝。

content 媒体项的 role ​

每个图片/视频/音频项必须携带 role，缺失会被拒绝（InvalidParameter: role must be specified for image contents）。取值：

role适用说明
first_frame图片/视频首帧
last_frame图片/视频尾帧，可与 first_frame 组合
reference_image图片参考图，最多 9 张
reference_video视频参考视频，最多 3 段
reference_audio音频参考音频，最多 3 个

样片两步流（draft 模式，2.5） ​

Step 1 出样片："draft": true，仅支持 480p，快速预览镜头与动作：

bash
curl $URL/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [ { "type": "text", "text": "霓虹街头，镜头缓慢推进" } ],
    "draft": true, "resolution": "480p", "duration": 4
  }'

Step 2 样片转正片：只传样片任务 ID，无需再带文本，提示词 / 参考素材等由模型自动复用。 正片分辨率固定 1080p（官方两档设计：样片 480p / 正片 1080p），须显式携带 resolution: "1080p"——不带 resolution 的裸 Step 2 会被以 resolution 无效拒绝：

bash
curl $URL/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [ { "type": "draft_task", "draft_task": { "id": "<Step1 返回的任务 ID>" } } ],
    "resolution": "1080p"
  }'
  • 样片任务 ID 有效期 7 天（自创建起算）；
  • 只能引用本人名下的样片任务。

请求示例 ​

文生视频 ​

bash
curl $URL/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [
      { "type": "text", "text": "一只戴着墨镜的猫走在霓虹灯街道上，镜头缓慢推进" }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

图生视频（引用素材库素材） ​

bash
curl $URL/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-260128",
    "content": [
      { "type": "text", "text": "让画面中的图案发光，镜头缓慢推近" },
      { "type": "image_url", "image_url": { "url": "素材库返回的素材 URL" }, "role": "first_frame" }
    ],
    "resolution": "720p",
    "duration": 5
  }'

图片项 role 按用途选择：以图片为首帧驱动运镜用 first_frame；作为主体/风格参考（不锁定首帧）用 reference_image。素材上传与管理见 素材库。

视频参考生视频（V2V 续写） ​

传入一段已有视频作为参考进行续写/演化，视频项 role 用 reference_video：

bash
curl $URL/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-260128",
    "content": [
      { "type": "text", "text": "延续参考视频的镜头运动与人物动作，场景切换到黄昏的海边，保持同样的调色风格" },
      { "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" }, "role": "reference_video" }
    ],
    "resolution": "720p",
    "duration": 5
  }'

参考视频时长计入输入 token（计费公式中的「输入视频时长」），带视频参考的任务按「视频参考」档单价计费；视频 URL 需公网可直连（可先用素材库转存取引用 URL）。

查询任务 ​

bash
curl $URL/api/v3/contents/generations/tasks/{task_id} \
  -H "Authorization: Bearer $YOUR_API_KEY"

状态机：queued → running → succeeded / failed / cancelled / expired。

字段类型说明
idstring任务 ID，cgt- 开头（官方样式任务 ID）
task_idstringid 的兼容别名，与 id 同值
upstream_idstring与 id 同值
modelstring模型名
statusstring上表状态机之一
content.video_urlstring成功时的结果视频 URL
usageobject实际用量（completion_tokens / total_tokens），计费以此为准
upstream_usageobject原始用量（对账参考）
errorobject失败时的 code / message
created_atinteger创建时间（Unix 秒）
completed_atinteger完成时间（Unix 秒）

取消任务 ​

bash
curl -X DELETE $URL/api/v3/contents/generations/tasks/{task_id} \
  -H "Authorization: Bearer $YOUR_API_KEY"
  • 排队中任务可取消，取消成功自动全额退款；
  • 已开始执行的任务以线路能力为准：上游允许则取消并退款，上游拒绝时任务继续执行至完成、按实际用量计费（响应会透传上游错误码）；
  • 已完成任务返回 409 TaskAlreadySucceeded；不存在的任务返回 404。

OpenAI 兼容入口（/v1/videos） ​

已有 OpenAI SDK / 客户端时可走统一入口 POST /v1/videos（查询 GET /v1/videos/{task_id}，响应为 OpenAI Video 风格）。该入口顶层参数遵循 OpenAI 语义，火山官方参数通过 metadata 字段透传，字段名与取值与官方一致。建议优先使用官方路径入口（见「端点」），本入口用于 OpenAI 形态兼容。

字段类型必填说明
modelstring是模型名
promptstring否文本提示词
secondsstring / integer否时长（秒），默认 5。注意 OpenAI 语义的时长参数是 seconds 而非 duration
imagesstring[]否参考图 URL 数组（单图默认 first_frame，多图默认 reference_image）
metadataobject否火山官方参数整体透传，支持本页「创建任务参数」表中的全部字段及 content 数组

注意：OpenAI 的 input_reference（图生视频）与 size（画幅）当前不生效——图生视频请用 metadata.content + role，画幅请用 metadata.resolution + metadata.ratio。

文生视频：

bash
curl $URL/v1/videos \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "prompt": "一只戴着墨镜的猫走在霓虹灯街道上",
    "seconds": "5",
    "metadata": { "resolution": "1080p", "ratio": "16:9" }
  }'

响应为 OpenAI Video 对象：id（cgt- 开头任务 ID）/ status（queued / in_progress / completed / failed）/ progress / created_at，完成后 metadata.url 为结果视频地址。

任务列表 ​

bash
curl "$URL/api/v3/contents/generations/tasks?page_num=1&page_size=10" \
  -H "Authorization: Bearer $YOUR_API_KEY"
参数类型说明
page_numinteger页码，从 1 起，默认 1
page_sizeinteger每页数量，1–100，默认 10
statusstring可选，按状态过滤：queued / running / succeeded / failed

响应：

json
{
  "items": [ { "id": "cgt-...", "task_id": "cgt-...", "status": "succeeded", "model": "...", "content": { "video_url": "..." }, "usage": { ... } } ],
  "total": 12,
  "page_num": 1,
  "page_size": 10
}

items 条目与单任务查询完全同格式；按时间倒序，仅返回本人的任务。

常见问题 ​

Q: 生成要多久？

文生视频通常 1–5 分钟；图生视频/带音频会更长（最长约 15 分钟）。任务超时上限 20 分钟，超时自动置为失败并退款。

Q: 计费为什么和预估不一致？

提交时按分辨率与时长预估预扣，完成后按实际 token 用量差额结算。图生视频通常只按输出时长计 token，实际扣费常低于预估。

Q: 返回 400 / 参数错误？

检查 content[] 结构是否符合官方格式（text / image_url / video_url / audio_url / draft_task）；图片/视频/音频项必须带 role；video_url 引用素材需先上传到素材库并处理完成。

© 2026 API-RUN 版权所有