Seedance 视频生成 — POST /v1/videos

使用 POST /v1/videos 创建异步 Seedance 视频生成任务。轮询任务直至完成，然后通过返回的 Flatkey 地址下载视频。支持的模型包括 seedance-2.0 和 seedance-2.0-fast。模型可用性取决于你的账户，请使用 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"。

array

必填

多模态输入数组。至少包含一条非空文本、一张图片或一段视频。

string

输出分辨率："480p"、"720p" 或 "1080p"。

string

输出画面比例："16:9"、"4:3"、"1:1"、"3:4"、"9:16"、"21:9" 或 "adaptive"。

integer

视频时长，范围为 4 至 15 秒。传入 -1 时由模型决定。

integer

随机种子。不传时使用随机种子。

boolean

是否添加水印。默认值：false。

boolean

是否生成同步音频。

`content` 元素

`type`	值字段	支持的 `role`	用途
`text`	`text`	—	文本提示词。多条文本会按顺序拼接。
`image_url`	`image_url.url`	`first_frame`、`last_frame`、`reference_image`	输入图或参考图，最多 9 张。
`video_url`	`video_url.url`	`reference_video`	参考视频，最多 3 段。
`audio_url`	`audio_url.url`	`reference_audio`	参考音频，最多 3 段。

当图片使用 first_frame 或 last_frame 角色时，API 会采用首尾帧模式；其他图片会作为参考图处理。

进阶参数

string

显式指定输入模式："reference" 或 "first_last_frame"。不传时根据 content 自动推断。

boolean

为任务启用联网搜索增强。

object

对生成视频进行超分，同时保留同一个公开任务 ID。

显示 super_resolution_config 字段

string

目标分辨率："720p"、"1080p"、"2k" 或 "4k"。目标必须高于原始分辨率，且不能与 resolution_limit 同时使用。

integer

自定义短边像素限制，范围为 64 至 2160。不能与 resolution 同时使用。

string

超分场景："aigc"、"short_series"、"ugc" 或 "old_film"。

string

超分模式："standard"（默认）或 "professional"。

integer

输出帧率，范围为 1 至 120。高于源帧率时会启用智能插帧。

camera_fixed、frames、callback_url 和 return_last_frame 为兼容目的而接受，但当前不会生效。

请求示例

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
}

多模态参考与画质超分

{
  "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,
  "super_resolution_config": {
    "resolution": "4k",
    "scene": "aigc",
    "tool_version": "professional",
    "fps": 60
  }
}

响应

{
  "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"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

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

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

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

状态值

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

下载视频

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 数据。该端点不需要 Bearer token，也可以直接作为 <video> 的资源地址。

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

错误

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

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

场景	行为
`content` 为空	请求会被拒绝。请提供非空文本、图片或视频。
模型不可用	请求的 `model` 未对当前路由开放。
余额不足	任务不会创建。
服务暂时不可用	请按常规退避策略稍后重试。

端到端示例

下面的示例会创建任务、每五秒轮询一次，并在任务完成后下载视频。运行前需要安装 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` 元素

进阶参数

请求示例

首尾帧输入

多模态参考与画质超分

响应

响应字段

查询任务状态

状态值

下载视频

错误

端到端示例