Seedance 视频接入

接入地址与鉴权

API Base：https://api.ziyelian.site/v1。请在控制台创建对应分组的 API Key。调用本站的模型目录、视频任务、本站下载接口与素材管理接口时，需携带请求头 Authorization: Bearer YOUR_API_KEY；POST 请求使用 Content-Type: application/json。

调用分组由 API Key 决定。Seedance【官转】 与 Seedance【官转·nswf】 两个分组均返回官方原始视频链接；2.0 Fast、2.0 Mini 使用 720p，2.0、2.5 可选 720p、1080p。视频生成为异步任务：提交创建请求后，请保存返回的任务 id，使用同一用户、同一分组的 API Key 持续查询原任务至终态，生成成功后下载并保存视频。

下载 Python 完整示例 · 下载创建请求 JSON · 查看模型广场

模型与价格

下表为当前两个分组的最终单价，单位：元 / 百万计费 Token。表中单价已计入折扣与所属分组倍率，计算费用时按“计费 Token 数 ÷ 1,000,000 × 表中单价”直接核算，无需再次乘折扣或倍率。价格更新以模型广场为准。

两个分组均提供官方原始视频链接。请求时请使用包含日期后缀的完整 model 名称；当前 Key 可用的模型目录可通过 GET /v1/models 获取。

接口清单

独立素材库的创建、查询与管理接口详见下方 素材库管理与引用 章节。

创建任务

将以下内容保存为 request.json。创建视频会产生付费任务，一笔业务订单只提交一次。

{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {"type": "text", "text": "A blue ball rests on a plain white table, static camera."}
  ],
  "duration": 4,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": false,
  "watermark": false
}

export ZHIYE_API_KEY='YOUR_API_KEY'
export API_BASE='https://api.ziyelian.site/v1'

curl --fail-with-body --silent --show-error --max-time 120 \
  "$API_BASE/contents/generations/tasks" \
  -H "Authorization: Bearer $ZHIYE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json \
  -o create.json

创建响应结构示例：

{"id":"task_example","status":"queued"}

task_example 是占位值，查询时请替换为真实响应的 id。创建请求遇到网络超时或结果不明时，请保留请求时间、原请求及响应内容先进行订单核对，不要自动重复发送 POST 请求。

查询任务

请保存创建响应中的任务 id，每隔 5～20 秒查询一次。重复查询同一 id 读取的是同一任务，不会创建新的生成订单；最终费用按该任务的实际用量结算。

export TASK_ID='创建响应中的真实 id'
curl --fail-with-body --silent --show-error \
  "$API_BASE/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $ZHIYE_API_KEY" \
  -o result.json

成功响应主要字段示例：

{
  "id": "task_example",
  "model": "doubao-seedance-2-5-260628",
  "status": "succeeded",
  "duration": 4,
  "resolution": "720p",
  "ratio": "16:9",
  "usage": {
    "total_tokens": 83505,
    "completion_tokens": 83505
  },
  "content": {
    "video_url": "OFFICIAL_VIDEO_URL"
  },
  "doubao-id": "cgt-example"
}

OFFICIAL_VIDEO_URL 为示例占位值，实际响应中的 content.video_url 是完整的官方签名视频链接。当结果包含 content.last_frame_url 时，可按相同方式获取末帧。usage 记录该任务的生成用量。

官链与任务溯源

两个 Seedance 分组均提供官方原始视频链接，并在任务结果包含关联标识时保留 doubao-id。请将任务 id、关联标识、完整响应结果和用量一并保存在私有订单记录中，不要只提取视频地址而丢弃其他字段。

字段名包含连字符，准确写作 doubao-id（JavaScript 使用 result['doubao-id']，Python 使用 result.get('doubao-id')）。请勿将 doubao-id 与本站查询路径中的 id 互换。关联标识与视频链接请私密保存，用于任务记录、核对与下载；公开展示或截图时请隐藏签名参数。

通过官方原链下载

从任务成功响应中读取 content.video_url，即可直接下载官方原始视频。该链接通过 URL 签名参数鉴权，下载时不要附加本站 API Key。

VIDEO_URL="$(python3 -c 'import json; print(json.load(open("result.json"))["content"]["video_url"])')"
curl --fail --silent --show-error --proto '=https' --max-time 180 \
  --url "$VIDEO_URL" \
  -o result.mp4

官方签名链接有有效期，请在生成完成后及时下载并保存至自有存储，不要将临时签名链接当作永久存储地址。

可选：本站任务下载接口

需要统一通过本站地址下载时，可使用任务 id 调用本站下载接口。仅此方式需要向本站发送 API Key：

curl --fail --silent --show-error --max-time 180 \
  "https://api.ziyelian.site/v1/tasks/$TASK_ID/artifacts/video/content" \
  -H "Authorization: Bearer $ZHIYE_API_KEY" \
  -o result.mp4

需要末帧且任务已生成末帧时，将本站下载路径中的 video 替换为 last_frame。

创建参数

按具体模型选择参数。两个分组使用相同的模型参数范围；分组价格见上表，分辨率按型号区分。

模型参数范围

2.0 Fast、2.0 Mini：720p；2.0、2.5：720p / 1080p。以下时长均以秒为单位，显式指定时使用整数；duration=-1 表示由模型在对应范围内选择时长。

视频帧率为 24 fps。查询结果中的 duration 是整数秒近似值，成片时长可能包含小数；视频编辑的时长由输入视频决定。

请求结构与类型

创建请求使用有效的完整模型名与非空 content 数组。按顺序传入素材，并准确设置 role；素材地址保留完整签名参数。布尔值填写 JSON 的 true / false，时长、优先级等填写数字。仅传入所选模型和任务类型定义的字段与取值。

参考素材与编辑

在 content 中按顺序加入文本与素材条目。素材 URL 使用可访问的 HTTPS 地址，链接有效期需覆盖生成过程；也可引用本用户、本 API 分组素材库中状态为 Active 的 asset://素材ID。

参考素材数量

2.0 系列的音频参考需搭配至少一张图片或一段视频；2.5 可使用音频作为独立参考素材。提示词按素材类型和顺序引用，例如“图片1”“视频1”，不要用素材 ID 代替提示词中的引用序号。

首帧与首尾帧

首帧生视频传入一张 first_frame 图片；首尾帧生视频分别传入一张 first_frame 和一张 last_frame 图片。首尾帧模式与全模态参考模式分别配置。2.5 的首帧、首尾帧模式均使用 ratio="adaptive"，保持首帧图片的宽高比。

2.0 系列参考、编辑与延长

2.0、Fast、Mini 可通过参考素材与提示词表达生成、编辑或延长意图，按各型号的分辨率和 4～15 秒时长范围配置；ratio 可选具体比例或 adaptive。

Seedance 2.5 任务模式

• reference：参考素材生成视频，可指定目标比例与 4～30 秒时长，也可使用自动比例与智能时长。
• edit：包含待编辑的参考视频，参考视频为 4～30 秒；填写 ratio="adaptive"、duration=-1，并在提示词中表达编辑意图。
• extend：包含待延长的参考视频，填写 ratio="adaptive"；输出视频时长填写 4～30 秒或 -1，提示词明确向前或向后延长。
• auto：结合输入素材与提示词判断任务类型；涉及参考视频时建议填写 ratio="adaptive"、duration=-1。

任务类型、提示词与参数应一致。创建响应仅表示任务已经提交，请持续查询至终态后读取结果。

素材库管理与引用

两个 Seedance 分组均提供独立的素材管理 API，适合复用项目素材、减少在视频请求中重复传递文件链接。完整使用流程分为四步：

1. 调用 /asset/groups 创建素材组，保存素材组 ID。
2. 调用 /asset/create 提交公网 HTTPS URL 导入素材，保存素材 ID。
3. 调用 /asset/get 查询素材状态，确认 Status 变为 Active。
4. 在创建视频请求的 content 中使用 asset://素材ID 引用该素材。

以下路径均相对于 https://api.ziyelian.site/v1，使用 POST、Content-Type: application/json 和本站 Bearer Key。素材管理接口仅接受下表所列字段及其明确的 SDK 别名，请勿传入其他未定义字段。

asset_type 可选 Image、Video、Audio，省略时默认为 Image。导入内容为 JSON 中的公网 HTTPS URL，文件由素材服务读取。列表分页默认第 1 页、每页 10 条，每页可设置 1～100 条。表中的 group_id 指素材组 ID，与 API Key 所属的控制台分组不同。

创建与重复提交保护

创建素材组（/asset/groups）和导入素材（/asset/create）必须携带稳定的请求头 Idempotency-Key。幂等键最多 256 个可见 ASCII 字符，由调用方按每个业务对象独立生成并稳定保存。

幂等作用域包含同一用户、同一 API 分组、同一操作、同一幂等键和相同请求正文：使用相同键和相同正文重放时，直接读取已记录结果；相同键搭配不同正文会返回 409 idempotency_conflict。若遇到网络异常或返回 seedance_asset_submission_pending，表示提交结果待核对，请保留原幂等键、原请求和响应进行核实，不要更换新键重复提交。此幂等键规则仅用于素材创建，不用于视频创建。

export API_BASE='https://api.ziyelian.site/v1'
export ZHIYE_API_KEY='YOUR_API_KEY'
# 每个业务对象使用独立、稳定的幂等键。
curl --fail-with-body --silent --show-error "$API_BASE/asset/groups" \
  -H "Authorization: Bearer $ZHIYE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: project-material-group-001' \
  --data '{"name":"项目素材","description":"参考镜头"}'

保存响应的 result.Id 为素材组 ID（GROUP_ID）。导入视频素材的请求结构如下：

{
  "group_id": "GROUP_ID",
  "url": "https://example.com/reference.mp4",
  "asset_type": "Video",
  "name": "参考镜头"
}

向 /asset/create 提交该 JSON，并携带新的素材专用 Idempotency-Key。保存返回的 result.Id 为素材 ID（ASSET_ID），再向 /asset/get 提交 {"id":"ASSET_ID"} 查询 result.Status。只有状态为 Active 的素材才可引用；素材入库与视频生成会分别进行校验。

{
  "type": "video_url",
  "video_url": {"url": "asset://ASSET_ID"},
  "role": "reference_video"
}

归属、查询与删除

• 同一用户、同一 API 分组的 Key 可使用该空间登记的素材，跨用户、跨分组相互隔离。
• 请使用创建素材时所属同一用户、同一分组的 Key 生成视频，并保持素材类型（Image / Video / Audio）与视频请求中的引用字段一致。
• 列表接口返回上次保存的素材信息。发起视频生成前，系统会重新检查所引用素材的当前状态；只有 Active 状态的素材可用于生成。
• 删除素材组会使组内素材引用失效。删除素材不是取消视频或退款操作；已提交的视频任务请继续按原任务 id 查询，实际结果以任务状态为准。
• 素材管理操作不新增本站视频生成扣款；引用素材创建视频时，仍按所选模型与分组单价及实际用量结算。
• 请确保所用素材具有合法使用授权，并妥善保管素材 ID、私有 URL 和 API Key。

SDK Action 兼容入口

支持 POST /v1/asset?Action=GetAsset&Version=2024-01-01。操作名为 CreateAssetGroup、ListAssetGroups、GetAssetGroup、UpdateAssetGroup、DeleteAssetGroup、CreateAsset、ListAssets、GetAsset、UpdateAsset、DeleteAsset，成功响应使用 Result 和 ResponseMetadata。REST 请求字段亦可使用大写开头的别名：Id、GroupId、Name、Description、URL、AssetType、PageNumber、PageSize；单次请求中同一字段只选择一种写法，不要同时发送两种写法。

/v1/asset/groups/list 返回 success / groups / total / page_number / page_size，其他 REST 操作使用 result 包装。兼容前缀 /api/v3/asset 的列表使用 result.Items / TotalCount / PageNumber / PageSize。所有入口均使用本站 Bearer Key。

计费与账单

计费 Token = usage.total_tokens
仅当 total_tokens 字段缺失时，读取 usage.completion_tokens
费用 = 计费 Token × 所选分组最终单价 ÷ 1,000,000

两个用量字段不相加。用量须为非负整数；遇到空值或类型异常时，请保留完整结果并核对账单。

以 100,000 个计费 Token 为例，Seedance 2.5 在 Seedance【官转】 分组下的费用为 ¥4.557，在 Seedance【官转·nswf】 分组下为 ¥4.90。这不是单条视频固定价格，任务用量由实际生成结果决定。

提交视频创建任务时会预扣估算额度，任务完成后按实际用量结算并调整差额。消费记录中可能同时出现预扣与退回记录，请以最终任务费用为准。重复查询同一任务读取的是既有记录，不会创建新的生成订单。

Python 完整示例

下载 seedance_client.py，仅使用 Python 标准库。支持单次创建、可恢复查询和本站鉴权下载。查询保存的 result.json 会保留官方原始视频链接；需要直接通过官链下载时，请按上方 通过官方原链下载 操作。订单目录中不保存 API Key。

export ZHIYE_API_KEY='YOUR_API_KEY'
python3 seedance_client.py --help
python3 seedance_client.py models

# 每笔新订单使用独立目录；create 只执行一次。
python3 seedance_client.py create request.json ./order-001
python3 seedance_client.py watch ./order-001 --wait-seconds 900
python3 seedance_client.py download ./order-001

查询等待窗口结束后，再次运行 watch 即可继续查询原任务；单次查看状态可使用 status ./order-001。请求、创建结果与最终查询结果会分别保存在订单目录中，下载的视频保存为 result.mp4。

Windows PowerShell 设置环境变量：

$env:ZHIYE_API_KEY = "YOUR_API_KEY"
python seedance_client.py models

JavaScript 查询示例

使用 Node.js LTS，在服务端设置环境变量 ZHIYE_API_KEY 和 ZHIYE_TASK_ID。以下示例只查询已创建的任务，不会创建新视频任务。

const base = 'https://api.ziyelian.site/v1';
const key = process.env.ZHIYE_API_KEY;
const taskId = process.env.ZHIYE_TASK_ID;
if (!key || !taskId) throw new Error('请设置 ZHIYE_API_KEY 和 ZHIYE_TASK_ID');

const response = await fetch(
  `${base}/contents/generations/tasks/${encodeURIComponent(taskId)}`,
  {
    headers: { Authorization: `Bearer ${key}`, Accept: 'application/json' },
    redirect: 'error',
    signal: AbortSignal.timeout(60000)
  }
);
if (!response.ok) throw new Error(`查询失败 HTTP ${response.status}`);
const result = await response.json();
const taskTrace = result['doubao-id'];
const officialVideoUrl = result.content?.video_url;
console.log({ id: result.id, status: result.status, traceAvailable: Boolean(taskTrace) });
// 将完整 result 保存到私有订单存储；不要公开签名链接或 API Key。

HTTP 状态约定

创建与查询请分开处理重试：查询遇到异常时可稍后继续查询原 id；视频创建结果不明时请先核对订单，避免盲目重发导致重复生成。请妥善保存 HTTP 状态码、响应正文和请求标识，并保管好 API Key 与私有素材地址。