Seedance 方舟原生接口

本页仅描述 Seedance 方舟原生接口，路径与 JSON 参数遵循火山方舟协议。它与Seedance 方舟原生素材库版是独立模式：API Base、任务、Endpoint 绑定分别使用，本页接口不能访问素材库版任务或引用其素材。

列表只返回当前账户有权访问的本地任务，不查询上游账户的全量任务。

模型

四个模型分辨率默认 720p，比例默认 adaptive；2.5 时长默认 -1；省略控制参数时保留模型侧默认行为。model 也可填平台管理员已绑定的 Endpoint ID；其他账户的 Endpoint ID 和素材 ID 不能直接迁移使用。实际开放状态与销售价格以账户获准使用的模型及平台价格配置为准。

快速开始

curl https://api.vibelab.me/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [{"type":"text","text":"A paper boat sails across a quiet lake"}],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": true,
    "return_last_frame": true
  }'

成功返回 HTTP 200：

{"id":"task_<任务标识>"}

这个 id 原样使用上游创建接口返回的网关任务 ID（task_...），不添加前缀或替换为自定义 UUID。保存它：查询、列表、回调都用同一个 ID。创建是异步的，返回 ID 只表示已接单，不代表视频已生成。

模式选择

首帧、首尾帧、全模态参考三个场景互斥。

请求参数

• 附加生成参数及未列出的扩展字段默认透传，保留 false、0、null、数组及嵌套对象，不再按参数白名单静默丢弃。已列出参数仍检查基本类型；支持范围、枚举及参数组合由模型服务进一步校验。
• 平台仍校验模型权限、content、分辨率、时长、比例、音频/草稿模式、任务有效期及回调地址等路由和计费所需字段。callback_url 由平台处理；转发时可按上游协议转换 duration 等字段名。
• 参数被接受并透传，不代表模型服务支持或保证生效；上游可能拒绝，也可能忽略该参数。
• 省略参数与显式 false、0、-1 含义不同。
• resolution、ratio、duration 等也可在文本末尾用 --参数 值 弱校验写法传入；顶层参数优先，提示词原样交给模型处理。建议用顶层强校验方式。

content 输入

• 图片、音频：公网 URL、对应 MIME 的 Base64 数据 URL、本模式获准使用的 asset:// 素材（不能用素材库版返回的公开 Asset Id）。视频：公网 URL 或 asset://，不支持 Base64。
• 公网素材须无需登录即可访问，并在生成完成前保持有效。整个请求体上限 64 MiB。
• 首帧、首尾帧、全模态参考三个场景互斥。首尾帧必须同时有一张 first_frame 和一张 last_frame；参考素材可组合图片、视频、音频。
• 2.0 系列不能仅提供音频，至少还需一张图或一个视频；2.5 支持纯音频参考。
• 2.5 视频、音频各类总时长不得超过 30 秒，2.0 系列不得超过 15 秒。数量通过不代表总时长合规，素材规格和总时长仍由生成服务检查。

请求示例

指定随机种子

seed 必须是 JSON 整数（例如 42 或 0），不能传字符串、小数或 null。省略时不注入默认值；模型服务决定具体取值范围和生成效果。固定种子不保证重复请求生成完全相同的视频。

{
  "model": "doubao-seedance-2-0-260128",
  "content": [{"type": "text", "text": "城市的清晨，街道人流缓缓移动，镜头保持静止"}],
  "resolution": "480p",
  "duration": 4,
  "ratio": "16:9",
  "seed": 42
}

首尾帧

2.5 首帧、首尾帧必须 adaptive；不会把显式宽高比静默改成 adaptive。

{
  "model":"doubao-seedance-2-5-260628",
  "content":[
    {"type":"text","text":"The scene gradually changes from dawn to sunset"},
    {"type":"image_url","role":"first_frame","image_url":{"url":"https://example.com/first.jpg"}},
    {"type":"image_url","role":"last_frame","image_url":{"url":"https://example.com/last.jpg"}}
  ],
  "ratio":"adaptive",
  "duration":5
}

编辑和延长

• 编辑：必须有 reference_video，ratio 必须 adaptive，duration 必须 -1，待编辑视频 4–30 秒。
• 延长：必须有 reference_video 和 adaptive 比例，时长可为 4–30 或 -1。
• 设为 auto 时模型自行判断任务类型。提交成功后仍可能因类型与参数不匹配而异步失败，检查终态 error。

{
  "model":"doubao-seedance-2-5-260628",
  "content":[
    {"type":"text","text":"Change the background of the reference video to a garden"},
    {"type":"video_url","role":"reference_video","video_url":{"url":"https://example.com/reference.mp4"}}
  ],
  "omni_reference_task_type":"edit",
  "ratio":"adaptive",
  "duration":-1,
  "output_format":"mov"
}

草稿与正式视频

第一步：2.5、draft:true、resolution:"480p" 创建草稿并等待成功。第二步：把成功草稿的公开 ID 作为 draft_task.id：

{
  "model":"doubao-seedance-2-5-260628",
  "content":[{"type":"draft_task","draft_task":{"id":"task_<草稿任务标识>"}}],
  "resolution":"1080p",
  "output_format":"mov",
  "return_last_frame":true
}

• 正式视频默认且仅支持 1080p；draft 必须省略或为 false。
• 提示词、输入素材、duration、ratio、seed、generate_audio、omni_reference_task_type 自动复用草稿，不得再次传入。其他允许字段可重新指定，省略按模型默认。
• 草稿须属于当前账户、已成功、使用同一模型，且仍在七天查询窗口内。
• 草稿和正式视频是独立任务，分别收费；正式视频继承草稿是否含参考视频的计价类别。

Python SDK

import os
import time
from arkruntime import Ark

client = Ark(
    base_url="https://api.vibelab.me/api/v3",
    api_key=os.environ["LOOPTOKEN_API_KEY"],
)

task = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-mini-260615",
    content=[{"type":"text","text":"A paper boat sails across a quiet lake"}],
    duration=4,
    resolution="480p",
)

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = client.content_generation.tasks.get(task_id=task.id)
    if result.status == "succeeded":
        print(result.content.video_url)
        break
    if result.status in {"failed", "expired", "cancelled"}:
        raise RuntimeError(result.error)
    time.sleep(5)
else:
    raise TimeoutError(f"Continue querying existing task {task.id}")

响应

创建成功返回 HTTP 200 和 {"id":"task_<任务标识>"}，见快速开始。用该 id 查询任务；状态 queued、running 继续轮询，succeeded、failed、expired、cancelled 为终态。

查询任务

curl "https://api.vibelab.me/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY"

{
  "id":"task_<任务标识>",
  "model":"doubao-seedance-2-5-260628",
  "status":"succeeded",
  "cgt_id":"cgt-<火山任务标识>",
  "content":{
    "video_url":"https://example.com/result.mp4",
    "last_frame_url":"https://example.com/result-last-frame.jpg"
  },
  "error":null,
  "duration":5,
  "resolution":"720p",
  "ratio":"16:9",
  "framespersecond":24,
  "generate_audio":true,
  "usage":{"completion_tokens":108900,"total_tokens":108900},
  "created_at":1791130000,
  "updated_at":1791130060
}

• 可选字段按实际任务响应返回。seed 仅在模型服务返回时透传，不会用请求值伪造响应；frames 不主动构造。Token 用量不会被隐藏，也不会把 admission 预估值当实际用量返回。
• queued、running 时每 5–10 秒继续查询；succeeded 读 content；failed、expired、cancelled 均为终态。HTTP 200 可能携带失败任务，必须检查 status。
• 任务记录仅在最近七天滚动窗口可查，窗口为 [当前 UTC 秒时间戳 - 7 天, 当前 UTC 秒时间戳)。
• 视频和尾帧 URL 有效期 24 小时，请及时下载。生成服务的下载次数限制仍然适用，2.5 视频最多下载 100 次。

查询列表

curl --get https://api.vibelab.me/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
  --data-urlencode 'page_num=1' \
  --data-urlencode 'page_size=20' \
  --data-urlencode 'filter.status=succeeded' \
  --data-urlencode "filter.task_ids=$TASK_ID_1" \
  --data-urlencode "filter.task_ids=$TASK_ID_2"

响应 {"total":整数,"items":[任务查询对象]}。total 为筛选后的总数；超过最后一页时 items 为 []，total 仍保留。按创建时间倒序，创建时间相同按任务 ID 定序。旧 /v1 任务不会混入。

回调

callback_url 接收 POST JSON，结构与任务查询相同，使用同一个公开任务 ID。排队、运行、成功、失败、过期等状态变化可产生回调。

• 接收端需在 5 秒内返回 2xx；失败最多尝试三次，间隔 30 秒。接收端应按 id 和 status 幂等处理。
• callback_url 必须是 HTTPS 公网地址，不能指向回环、内网或元数据地址，不接受重定向。也可以只用轮询。

计费

• 公式：费用 = Token 用量 / 1,000,000 × 对应档位 Token 单价 × 账户折扣。按实际 usage.completion_tokens 扣费。
• 默认折扣系数 1（原价），0.8 为八折；模型专属折扣覆盖通用折扣，不叠乘。已配置的原生专属绝对价格优先，也不叠加折扣。
• Token 单价按模型、输出分辨率、输入是否含参考视频分档。参考视频的输入总时长会影响计费用量，并非按文件个数固定加价；不要在 completion_tokens 上再加一次输入视频用量。缺少计费用量时不会按零元结算。
• 生成前按已配置销售档位预扣，成功后按实际用量结算，失败/过期释放预扣。预扣不是最终费用。
• 预扣按请求时长和分辨率估算输出用量（24 fps）；未指定或自动时长先按 5 秒估算，不用模型最大时长或统一 4K 预算。估算像素预算：480p 854×480、720p 1280×720、1080p 1920×1080、4k 3840×2160。实际宽高、参考视频用量和自动时长以生成服务返回为准，结算时补退差额。
• 提交时锁定价格版本和折扣，执行期间改价不影响该任务。草稿与正式视频分别结算。
• 与Seedance 方舟原生素材库版共用同一套 Token 基础价格，但两种模式的账户和模型折扣分别配置，互不继承。
• 积分换算 10 积分 = 1 美元（1 积分 = ¥0.7）；正数金额按平台精度向上取整，最低扣费 0.001 积分；最终费用以账户账单为准。

错误

HTTP 错误体：{"error":{"code":"...","message":"..."}}。

常见 400 的 message：

注意事项

• 视频和尾帧 URL 24 小时过期；任务记录七天后不可查 → 及时下载转存。
• 2.5 首帧/首尾帧/编辑/延长必须 adaptive，编辑还必须 duration: -1 → 按此传参。
• 草稿转正式视频时，已自动复用的字段（提示词、素材、duration、ratio、seed、generate_audio、omni_reference_task_type）→ 不得再次传入。
• 本模式的 Endpoint ID、素材 ID 不能与素材库版互用。