Seedance 视频生成 — POST /v1/videos

使用 POST /v1/videos 创建异步 Seedance 视频生成任务。轮询任务直至完成，然后通过返回的 Flatkey 地址下载视频。支持的模型有 seedance-2.0、seedance-2.0-fast、seedance-2.0-mini 和 seedance-2.5。模型可用性取决于你的账户，请使用 GET /v1/models 获取当前模型列表。

端点

POST https://router.flatkey.ai/v1/videos

Flatkey 也支持 POST /v1/video/generations 和 GET /v1/video/generations/{task_id}。推荐使用 /v1/videos，以获得标准响应结构和原生 usage 数据。

请求

请求头

请求头	值
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

请求体参数

string

必填

Seedance 模型 ID："seedance-2.0"、"seedance-2.0-fast"、"seedance-2.0-mini" 或 "seedance-2.5"。

array

必填

多模态输入元素。至少包含一条非空文本、图片、视频或音频。见 content 元素。

string

输出分辨率，默认 "720p"。

模型	支持的值
`seedance-2.0`	`"480p"`、`"720p"`、`"1080p"`、`"4k"`
`seedance-2.0-fast`、`seedance-2.0-mini`	`"480p"`、`"720p"`
`seedance-2.5`	`"480p"`、`"720p"`、`"1080p"`

string

输出宽高比："16:9"、"4:3"、"1:1"、"3:4"、"9:16"、"21:9" 或 "adaptive"，默认 "adaptive"。设为 "adaptive" 时，模型根据输入的图片或视频自动选择比例。seedance-2.5 的首帧和首尾帧任务只支持 "adaptive"。

integer

视频时长（秒），默认 5。Seedance 2.0 系列支持 4 至 15；seedance-2.5 支持 4 至 30。

请始终传正数 duration。Flatkey 对 Seedance 按秒计费，-1（由模型自行决定时长）会被拒绝并返回 video_price_not_configured。唯一例外是 seedance-2.5 视频编辑，它要求传 -1。

boolean

是否在右下角添加 “AI generated” 水印，默认 false。

boolean

是否生成同步的单声道音频，默认 true。只需要画面时设为 false；生成的音频偶尔会因版权检测导致任务失败。

boolean

是否以图片形式返回生成视频的最后一帧，默认 false。设为 true 时，任务完成后响应中会带 metadata.last_frame_url，可下载与视频尺寸相同、无水印的 JPEG。把它作为下一个任务的 first_frame，即可实现多段续接。与 metadata.url 一样，下载无需鉴权头，请妥善保管该地址。

string

仅 seedance-2.5。生成视频的封装格式："mp4" 或 "mov"，默认 "mp4"。MOV 色彩精度更高，适合调色、抠像、合成等后期（H.264、YUV 4:4:4、PCM 音频），但部分播放器无法打开。MOV 结果通过内容端点下载时返回 video/quicktime。

string

仅 seedance-2.5 的参考模式任务。告诉模型你要做哪类任务："auto"（默认）、"reference"、"edit" 或 "extend"。显式指定后，任务类型相关的校验会提前到提交时进行，不合法的组合会立即报错，而不是任务开始后才失败。"reference"、"edit"、"extend" 都要求 content 中有参考素材；只有文本却指定 "reference" 会被拒绝。详见视频编辑与延长。

integer

排队优先级，取值 0 至 9，默认 0。数值越大，越会排在同一模型下优先级更低的任务之前。Seedance 2.0 全系列和 seedance-2.5 支持。超出 0–9 会返回 400。

integer

任务从创建起最多等待和运行的秒数，超时即过期。默认 172800（48 小时）。如果结果来得太晚就没有用，可以设得更短。

string

公网 HTTPS 地址，任务状态每次变化时都会收到一次 POST，详见任务回调。必须使用 https、不能包含用户名密码、长度不超过 2048 个字符，并且解析到公网地址，否则请求返回 400。

`content` 元素

`type`	值字段	支持的 `role`	限制
`text`	`text`	—	提示词，建议不超过 500 个汉字。
`image_url`	`image_url.url`	`first_frame`、`last_frame`、`reference_image`	参考图最多 9 张（`seedance-2.5` 为 30 张）。支持 JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF；单张小于 30 MB；每边 300–6000 像素；宽高比 0.4–2.5。
`video_url`	`video_url.url`	`reference_video`	最多 3 段，每段 2–15 秒、合计不超过 15 秒（`seedance-2.5` 为 10 段、合计 30 秒）。MP4 或 MOV；小于 200 MB；总像素至少约 409,600（例如 854×480）。
`audio_url`	`audio_url.url`	`reference_audio`	最多 3 段，每段 2–15 秒、合计不超过 15 秒（`seedance-2.5` 为 10 段、合计 30 秒）。WAV 或 MP3；小于 15 MB。Seedance 2.0 系列不能只传音频，需同时提供至少一张图片或一段视频。

每个 URL 可以是公网 HTTPS 地址、data:<mime>;base64, 格式的 data URI（仅图片和音频），或者素材库中的 asset:// 引用。整个请求体不得超过 64 MB。每个任务只能选择一种输入模式，不能混用：

模式	`content` 写法
首帧	一张 `role: "first_frame"` 的图片。
首尾帧	两张图片，分别为 `role: "first_frame"` 和 `role: "last_frame"`。`last_frame` 必须和 `first_frame` 一起使用，且两者都不能与参考类素材混用。
参考	`reference_image`、`reference_video`、`reference_audio` 任意组合。

视频编辑

seedance-2.5 可以在参考模式下编辑或延长已有视频。在提示词里描述要做的改动，并用 @Video1 指代该视频。

任务	必须的设置	输出时长
编辑（替换主体、增删物体、修改音频）	至少一段 4–30 秒的 `reference_video`，`ratio: "adaptive"`，`duration: -1`。建议加 `omni_reference_task_type: "edit"`。	与被编辑的输入视频相同
延长（向前或向后续写视频）	至少一段 `reference_video`，`ratio: "adaptive"`，`duration` 为正数。建议加 `omni_reference_task_type: "extend"`。	`duration`

{
  "model": "seedance-2.5",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "content": [
    { "type": "text", "text": "Edit @Video1: make the ball bright green and keep everything else unchanged." },
    { "type": "video_url", "video_url": { "url": "https://example.com/input.mp4" }, "role": "reference_video" }
  ]
}

和所有带参考视频的 seedance-2.5 请求一样，编辑按对应分辨率的带视频单价、固定 30 秒计费，与输入、输出视频的实际时长无关。

样片模式

seedance-2.5 可以先生成一个便宜的 480p 样片，确认场景、镜头和动作没问题后，再花钱出正式视频。共需两次请求：

生成样片。 按正常请求发送，加上 "draft": true 和 "resolution": "480p"，按普通 480p 视频计费。
生成正片。 样片完成后再发一次请求，content 中只放一个指向样片任务 ID 的 draft_task，并设置 "resolution": "1080p"。

{
  "model": "seedance-2.5",
  "resolution": "1080p",
  "content": [
    { "type": "draft_task", "draft_task": { "id": "task_3f9a00000000000000000000000000e2" } }
  ]
}

正片会沿用样片的提示词、素材、时长、宽高比、seed、音频设置和任务类型。带 draft_task 时不能再传 duration、ratio、frames、seed、generate_audio、omni_reference_task_type、draft，也不能有其他 content 元素，否则返回 400。return_last_frame、output_format、watermark、priority、execution_expires_after 和 callback_url 仍可设置。

规则	说明
模型	`model` 必须与样片一致。
样片任务 ID	使用 Flatkey 为样片返回的 `task_…` ID，必须是你自己的、且已成功完成的任务。
分辨率	样片只能 `480p`，正片只能 `1080p`。
有效期	样片创建后 7 天内可用于生成正片。
计费	正片按 1080p 单价、样片的时长计费。样片使用了参考视频时，按带视频单价固定 30 秒计费。

Seedance 不接受直接上传含真人人脸的图片或视频。请先上传为真人素材，再用 asset:// 引用。

请求示例

import os
import requests

response = requests.post(
    "https://router.flatkey.ai/v1/videos",
    headers={
        "Authorization": f"Bearer {os.environ['FLATKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2.0",
        "content": [
            {
                "type": "text",
                "text": "宇航员在月球漫步，电影感，镜头缓慢推近",
            }
        ],
        "resolution": "1080p",
        "ratio": "16:9",
        "duration": 5,
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://router.flatkey.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLATKEY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.0",
    content: [
      {
        type: "text",
        text: "宇航员在月球漫步，电影感，镜头缓慢推近",
      },
    ],
    resolution: "1080p",
    ratio: "16:9",
    duration: 5,
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

curl https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "宇航员在月球漫步，电影感，镜头缓慢推近"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

首尾帧输入

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "镜头缓缓向前推进" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.jpg" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last.jpg" },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false
}

多模态参考

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "女孩对着镜头微笑，背景是海边日落" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference.jpg" },
      "role": "reference_image"
    }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": false
}

响应

{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1780306574
}

响应字段

string

用于轮询任务和下载完成视频的公开任务 ID。task_id 包含相同的值。

string

任务状态：queued、in_progress、completed 或 failed。

integer

生成进度，范围为 0 至 100。

integer

任务创建时的 Unix 时间戳。

查询任务状态

GET https://router.flatkey.ai/v1/videos/{task_id}

curl https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2 \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

任务生成过程中，响应会包含当前进度：

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "in_progress",
  "progress": 50,
  "model": "seedance-2.0",
  "created_at": 1780306574
}

任务完成后，响应会包含视频地址和 token 用量：

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content",
    "last_frame_url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/last-frame"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

失败任务会在任务响应中返回错误详情：

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "failed",
  "error": {
    "message": "视频生成任务失败。",
    "code": ""
  }
}

已预扣的余额会自动退还。

状态值

状态	含义
`queued`	任务正在排队等待。
`in_progress`	视频正在生成，`progress` 范围为 0 至 100。
`completed`	视频已生成，地址位于 `metadata.url`，token 用量位于 `usage`。
`failed`	生成失败，详情位于 `error.message`，已预扣的余额会自动退还。

任务回调

设置 callback_url 后，可以接收任务状态变化通知，替代轮询或与轮询配合使用。任务进入 in_progress、completed 或 failed 时，Flatkey 会以 Content-Type: application/json 发送一次 POST。请求体与此刻调用 GET /v1/videos/{task_id} 的返回完全一致，任务完成时包含 metadata.url 和 metadata.last_frame_url。

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

请求头	值
`X-Flatkey-Event-Id`	`<task_id>:<status>`，例如 `task_3f9a…e2:completed`。同一事件可能重复送达，请用这个请求头去重。

请在 5 秒内返回任意 2xx 状态码。否则 Flatkey 会在 2 秒和 8 秒后各重试一次，之后不再发送。不跟随重定向。回调没有签名，处理结果前请先查询任务确认；回调可能丢失，请以查询接口为准。

下载视频

GET https://router.flatkey.ai/v1/videos/{task_id}/content

curl -L "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content" \
  -o output.mp4

内容端点以流式方式返回 video/mp4 数据；任务使用 output_format: "mov" 时返回 video/quicktime。该端点不需要 Bearer token，也可以直接作为 <video> 的资源地址。

只有任务完成后才能访问内容端点，且该端点会按客户端 IP 限流。任何获得该 URL 的人都可以下载视频，请将它视为敏感信息。

错误

请求阶段的错误使用 Flatkey 标准错误结构：

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

场景	行为
`content` 为空	请求会被拒绝。请提供非空文本、图片或视频。
模型不可用	请求的 `model` 未对当前路由开放。
余额不足	任务不会创建。
`priority` 超出 0–9	请求返回 `400`，code 为 `invalid_request`。
`callback_url` 不合法	不是 HTTPS、包含用户名密码、超过 2048 个字符，或指向内网、本机地址时，请求返回 `400`，code 为 `invalid_request`。
非 `seedance-2.5` 视频编辑却传 `duration: -1`	请求返回 `400`，code 为 `video_price_not_configured`。
输入不符合模型限制	请求返回 `400` 和 `fail_to_fetch_task`；使用 `asset://` 引用的请求则是任务失败，错误为 `task preparation failed`。请对照上文的分辨率、时长、素材限制和输入模式规则检查。不会扣费。
服务暂时不可用	请按常规退避策略稍后重试。

端到端示例

下面的示例会创建任务、每五秒轮询一次，并在任务完成后下载视频。运行前需要安装 jq。

#!/usr/bin/env bash
set -euo pipefail

BASE="https://router.flatkey.ai"
: "${FLATKEY_API_KEY:?请先设置 FLATKEY_API_KEY}"

RESPONSE=$(curl -sS "$BASE/v1/videos" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      { "type": "text", "text": "宇航员在月球漫步，电影感" }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }')

TASK_ID=$(echo "$RESPONSE" | jq -r '.id')
echo "task: $TASK_ID"

while true; do
  RESULT=$(curl -sS "$BASE/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer $FLATKEY_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  echo "status: $STATUS"

  [ "$STATUS" = "completed" ] && break
  if [ "$STATUS" = "failed" ]; then
    echo "failed: $(echo "$RESULT" | jq -r '.error.message')" >&2
    exit 1
  fi
  sleep 5
done

VIDEO_URL=$(echo "$RESULT" | jq -r '.metadata.url')
curl -L "$VIDEO_URL" -o output.mp4
echo "saved -> output.mp4"

​端点

​请求

​请求头

​请求体参数

​content 元素

​视频编辑

​样片模式

​请求示例

​首尾帧输入

​多模态参考

​响应

​响应字段

​查询任务状态

​状态值

​任务回调

​下载视频

​错误

​端到端示例

端点

请求

请求头

请求体参数

`content` 元素

视频编辑

样片模式

请求示例

首尾帧输入

多模态参考

响应

响应字段

查询任务状态

状态值

任务回调

下载视频

错误

端到端示例