Seedance 视频生成

通过 XInfera 调用 Seedance 系列模型生成视频。接口采用异步任务流程：提交任务、轮询状态，然后下载生成的视频。

1. 开始之前

你需要一个 XInfera API Key，并确保该密钥可以访问 Seedance 模型。请把密钥保存在服务端，并从环境变量读取：

export XINFERA_API_KEY="sk-YOUR_API_KEY"

所有请求使用以下 API 地址：

https://api.xinfera.cn

2. 支持的模型

模型	支持的分辨率	适用场景
`doubao-seedance-2-5`	480p、720p、1080p	最长时长和最多参考素材
`doubao-seedance-2-0`	480p、720p、1080p、4K	最高分辨率，支持 4K 输出
`doubao-seedance-2-0-fast`	480p、720p	更快的生成速度
`doubao-seedance-2-0-mini`	480p、720p	轻量生成任务

Seedance 2.5 与 Seedance 2.0 的请求格式相同，差异有三点：

单次生成时长为 4-30 秒，上限高于 Seedance 2.0。
metadata.content 最多支持 30 张图片、10 段视频和 10 段音频。
4K 输出仍然只有 doubao-seedance-2-0 支持。

接入前请使用同一个 API Key 调用 GET /v1/models。接口返回结果是当前账号实际可用模型 ID 的准确信息来源。

3. 调用流程

调用 POST /v1/video/generations 提交生成任务。
轮询 GET /v1/video/generations/{task_id}，直到任务成功或失败。
保存 data.result_url，或通过 GET /v1/videos/{task_id}/content 下载视频。

4. 创建视频任务

POST https://api.xinfera.cn/v1/video/generations
Authorization: Bearer sk-YOUR_API_KEY
Content-Type: application/json

4.1 请求字段

字段	类型	必填	说明
`model`	string	是	支持模型表中的 Seedance 模型 ID。
`prompt`	string	是	非空的视频描述文本。
`images`	string[]	否	单张、简单的首帧参考图 URL 或 `asset://` 引用。不要与 `metadata.content` 同时传入。
`seconds`	string	否	视频时长（秒），例如 `"4"`；优先级高于 `metadata.duration`。
`metadata`	object	否	Seedance 专属生成参数和参考素材。

metadata 支持以下字段：

字段	类型	说明
`resolution`	string	`480p`、`720p`、`1080p` 或 `4k`。只有 `doubao-seedance-2-0` 支持 4K。
`ratio`	string	画面比例，例如 `16:9`、`9:16` 或 `1:1`。
`duration`	number	视频时长（秒）。顶层 `seconds` 的优先级更高。
`watermark`	boolean	是否添加水印。
`generate_audio`	boolean	是否同步生成音频。
`seed`	number	随机种子，固定后可以复现结果。
`service_tier`	string	服务优先级档位。
`content`	array	多张图片、视频或音频参考素材，可以通过 `role` 标注用途。

只能选择一种参考素材传法

不要同时传入 images 和 metadata.content。两者同时存在时，metadata.content 会替换由 images 转换的内容，而不是与其合并。只要涉及多素材、混合媒体或显式 role，就应把所有素材统一放进 metadata.content。

metadata.content 中每一项使用以下结构：

字段	说明
`type`	`image_url`、`video_url` 或 `audio_url`。
`image_url.url`、`video_url.url`、`audio_url.url`	可公开访问的参考素材 URL 或 `asset://` 引用。
`role`	可选用途标记，例如 `reference_image`、`reference_video` 或 `reference_audio`。

metadata.content 中的文本项会被忽略。最终文本指令必须写在顶层 prompt 字段中。

4.2 文生视频示例

curl https://api.xinfera.cn/v1/video/generations \
  -H "Authorization: Bearer $XINFERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast",
    "prompt": "一只猫在窗边悠闲地喝奶茶",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 4,
      "watermark": false,
      "generate_audio": false
    }
  }'

4.3 图生视频示例

最简单的单张首帧输入可以使用 images：

curl https://api.xinfera.cn/v1/video/generations \
  -H "Authorization: Bearer $XINFERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "画面中的场景开始下雪",
    "images": ["https://example.com/first-frame.png"],
    "metadata": {
      "resolution": "1080p",
      "duration": 5
    }
  }'

如果首帧已经上传到素材库，直接将 URL 替换为素材引用即可，例如 "images": ["asset://asset_XXXXXXXXXXXXXXXX"]。涉及真人或高度拟真人脸的参考素材必须通过素材库引用。

4.4 混合参考素材示例

多张图片或混合媒体场景，需要把所有参考素材放进 metadata.content。每一项可以独立使用公开 URL 或 asset:// 引用，因此两种方式可以在同一个请求中混用：

{
  "model": "doubao-seedance-2-0",
  "prompt": "生成第一人称视角的果茶广告，以图片 1 开场，以图片 2 结尾。",
  "metadata": {
    "content": [
      {
        "type": "image_url",
        "image_url": { "url": "asset://asset_pic1XXXXXXXXXXXXXXXXXXXX" },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/pic2.jpg" },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/reference.mp4" },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": { "url": "asset://asset_audioXXXXXXXXXXXXXXXXXXX" },
        "role": "reference_audio"
      }
    ],
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 11,
    "watermark": false
  }
}

在素材库上传文件或 URL 后，从素材详情中复制 asset://asset_... 引用。素材必须属于当前账号且未被删除。上传、分组和接口管理方法见素材库。

4.5 提交响应

提交成功后会立即返回排队中的任务：

{
  "id": "task_ICJ8cdkxbYGnaO7fNYiWdGhKUwz3UTeZ",
  "task_id": "task_ICJ8cdkxbYGnaO7fNYiWdGhKUwz3UTeZ",
  "object": "video",
  "model": "doubao-seedance-2-0-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1786341192
}

请保存 id 或 task_id；它们都是后续请求使用的任务标识。

5. 查询任务状态

curl https://api.xinfera.cn/v1/video/generations/task_ICJ8cdkxbYGnaO7fNYiWdGhKUwz3UTeZ \
  -H "Authorization: Bearer $XINFERA_API_KEY"

任务完成后的响应结构如下：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_ICJ8cdkxbYGnaO7fNYiWdGhKUwz3UTeZ",
    "status": "SUCCESS",
    "progress": "100%",
    "fail_reason": "",
    "result_url": "https://example.com/generated-video.mp4",
    "submit_time": 1786341192,
    "start_time": 1786341225,
    "finish_time": 1786341450,
    "properties": {
      "origin_model_name": "doubao-seedance-2-0-fast"
    }
  }
}

`data.status`	含义	下一步
`QUEUED`	等待开始	继续轮询。
`IN_PROGRESS`	正在生成	继续轮询。
`SUCCESS`	生成完成	保存 `result_url`，或通过内容接口下载。
`FAILURE`	生成失败	查看 `fail_reason`。

建议每 5-10 秒轮询一次，并且必须设置最大尝试次数或超时时间。不要在请求处理函数中运行没有上限的循环。

6. 下载视频

result_url 通常是可以直接下载的签名地址，有效期一般约为 24 小时。请及时保存文件，不要把该 URL 当作永久存储地址。

如果签名地址无法访问，可以使用需要认证的平台代理接口：

curl https://api.xinfera.cn/v1/videos/task_ICJ8cdkxbYGnaO7fNYiWdGhKUwz3UTeZ/content \
  -H "Authorization: Bearer $XINFERA_API_KEY" \
  --output seedance.mp4

7. 完整 Shell 示例

以下示例需要安装 jq：

# 步骤 1：提交生成任务，并取出任务 ID
TASK_ID=$(curl -s https://api.xinfera.cn/v1/video/generations \
  -H "Authorization: Bearer $XINFERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast",
    "prompt": "一只猫在窗边悠闲地喝奶茶",
    "metadata": {"resolution": "720p", "duration": 4}
  }' | jq -r '.id')

# 步骤 2：轮询任务状态，最多 120 次、每次间隔 5 秒（约 10 分钟）
for attempt in $(seq 1 120); do
  RESPONSE=$(curl -s \
    "https://api.xinfera.cn/v1/video/generations/$TASK_ID" \
    -H "Authorization: Bearer $XINFERA_API_KEY")
  STATUS=$(printf '%s' "$RESPONSE" | jq -r '.data.status')
  echo "status: $STATUS"

  # 步骤 3：生成成功，输出视频地址并结束轮询
  if [ "$STATUS" = "SUCCESS" ]; then
    printf '%s' "$RESPONSE" | jq -r '.data.result_url'
    break
  fi

  # 步骤 4：生成失败，输出失败原因并以非零状态码退出
  if [ "$STATUS" = "FAILURE" ]; then
    printf '%s' "$RESPONSE" | jq -r '.data.fail_reason' >&2
    exit 1
  fi

  sleep 5
done

8. 错误处理

HTTP 状态码	Code	说明
`400`	`invalid_request`	缺少必填字段或字段值不合法。
`400`	`model_price_error`	所选模型尚未配置价格。
`402`	-	账号余额不足。
`500`	`do_request_failed`	上游服务失败；请使用退避策略重试。

不要在浏览器代码、日志或公开仓库中暴露 API Key。生产环境应从服务端队列或 worker 提交和轮询任务。

1. 开始之前​

2. 支持的模型​

3. 调用流程​

4. 创建视频任务​

4.1 请求字段​

4.2 文生视频示例​

4.3 图生视频示例​

4.4 混合参考素材示例​

4.5 提交响应​

5. 查询任务状态​

6. 下载视频​

7. 完整 Shell 示例​

8. 错误处理​

Contents