Seedance 视频生成¶

支持文生视频、图生视频、首尾帧和多素材参考（图片 / 视频 / 音频），4-15 秒可选时长。

快速开始¶

# 1. 提交任务
curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-official",
    "prompt": "一只橘猫在花园里追逐蝴蝶，慢动作，电影级画质",
    "duration": 5,
    "metadata": {
      "ratio": "16:9"
    }
  }'

# 2. 轮询结果
curl https://cdn.12ai.org/v1/videos/{task_id} \
  -H "Authorization: Bearer $API_KEY"

可用模型¶

模型 ID	说明	默认分辨率	文生视频	图生视频	首尾帧	多素材参考	素材过审
`seedance-2-official`	标准版	480p	✅	✅	✅	✅	—
`seedance-2-official2-fast`	快速版	720p	✅	✅	✅	✅	自动

所有模型支持比例：21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
所有模型支持时长：4-15 秒
素材过审：seedance-2-official2-fast 已默认开启自动过审，直接传 URL 即可，无需提前处理
计费方式：按秒计费（单价 × 视频时长秒数）

通用说明¶

端点¶

视频生成使用系统统一的视频 API 端点（与 Sora、Kling、Vidu 等一致）：

方法	路径	说明
`POST`	`/v1/videos`	提交生成任务
`GET`	`/v1/videos/{task_id}`	查询任务状态

请求头¶

参数	值	说明
`Authorization`	`Bearer YOUR_API_KEY`	必填
`Content-Type`	`application/json`	POST 时必填

请求体结构¶

Seedance 视频生成通过 /v1/videos 提交，使用以下统一结构：

{
  "model": "seedance-2-official",
  "prompt": "提示词",
  "duration": 5,
  "size": "480p",
  "images": ["https://..."],
  "metadata": {
    "ratio": "16:9",
    "generate_audio": true,
    "web_search": false,
    "watermark": false,
    "webhook_url": "https://...",
    "video_urls": ["https://..."],
    "audio_urls": ["https://..."]
  }
}

基础参数¶

参数	类型	必填	说明
`model`	string	是	模型 ID
`prompt`	string	是	提示词，1-2500 字符
`duration`	number	否	时长（秒），4-15，默认 5
`size`	string	否	分辨率：`480p` 或 `720p`，默认见模型
`images`	string[]	否	图片 URL 数组（用于图生视频/首尾帧/多素材参考）

metadata 中的可选参数¶

以下 Seedance 特有参数通过 metadata 对象传递：

参数	类型	默认	说明
`ratio`	string	—	画面比例：`21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`
`generate_audio`	boolean	`true`	是否生成音频
`web_search`	boolean	`false`	文本增强搜索（仅 text_to_video）
`watermark`	boolean	`false`	是否添加水印
`webhook_url`	string	—	完成后回调 URL
`video_urls`	string[]	—	参考视频 URL（仅 multi_ref）
`audio_urls`	string[]	—	参考音频 URL（仅 multi_ref）

模式自动判断¶

系统根据 images 数组的长度自动判断生成模式，无需手动指定 mode：

images 长度	自动模式	说明
0 或不传	`text_to_video`	纯文本生成视频
1	`image_to_video`	单张图片作为首帧
2	`first_last_frame`	首帧 + 尾帧
≥ 3	`multi_ref`	多素材参考

也可以通过 metadata.action 手动指定模式。

模式一：文生视频 (text_to_video)¶

纯文本描述生成视频，无需图片。

参数¶

参数	类型	必填	说明
`model`	string	是	模型 ID
`prompt`	string	是	提示词，1-2500 字符
`metadata.web_search`	boolean	否	文本增强搜索，默认 `false`

示例¶

cURLPython

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-official",
    "prompt": "电影感特写，温馨木地板上的浅蓝色塑料收纳箱，柔和的自然阳光，4K",
    "duration": 5,
    "size": "480p",
    "metadata": {
      "ratio": "16:9"
    }
  }'

import requests

resp = requests.post(
    "https://cdn.12ai.org/v1/videos",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2-official",
        "prompt": "电影感特写，温馨木地板上的浅蓝色塑料收纳箱，柔和的自然阳光，4K",
        "duration": 5,
        "size": "480p",
        "metadata": {
            "ratio": "16:9",
        },
    },
)
print(resp.json())

提交响应示例¶

{
  "id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2-official",
  "status": "queued",
  "progress": 0,
  "created_at": 1775012564
}

提交成功后立即返回 queued 状态，通过 id 轮询后续进度。

模式二：图生视频 (image_to_video)¶

以一张图片作为视频首帧，AI 让画面"动起来"。

参数¶

参数	类型	必填	说明
`model`	string	是	模型 ID
`prompt`	string	是	提示词，1-2500 字符
`images`	string[]	是	恰好 1 张公网可访问的图片 URL

示例¶

cURLPython

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-official",
    "prompt": "让画面中的猫缓缓转头看向镜头",
    "images": ["https://example.com/cat.jpg"],
    "duration": 5,
    "metadata": {
      "ratio": "16:9"
    }
  }'

import requests

resp = requests.post(
    "https://cdn.12ai.org/v1/videos",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2-official",
        "prompt": "让画面中的猫缓缓转头看向镜头",
        "images": ["https://example.com/cat.jpg"],
        "duration": 5,
        "metadata": {
            "ratio": "16:9",
        },
    },
)
print(resp.json())

模式三：首尾帧 (first_last_frame)¶

指定首帧和尾帧，AI 生成中间的过渡动画。

参数¶

参数	类型	必填	说明
`model`	string	是	模型 ID
`prompt`	string	是	提示词，1-2500 字符
`images`	string[]	是	恰好 2 张图片 URL：`[首帧, 尾帧]`

示例¶

cURLPython

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-official",
    "prompt": "从白天平滑过渡到夜晚的延时效果",
    "images": [
      "https://example.com/day.jpg",
      "https://example.com/night.jpg"
    ],
    "duration": 5,
    "metadata": {
      "ratio": "16:9"
    }
  }'

import requests

resp = requests.post(
    "https://cdn.12ai.org/v1/videos",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2-official",
        "prompt": "从白天平滑过渡到夜晚的延时效果",
        "images": [
            "https://example.com/day.jpg",
            "https://example.com/night.jpg",
        ],
        "duration": 5,
        "metadata": {
            "ratio": "16:9",
        },
    },
)
print(resp.json())

模式四：多素材参考 (multi_ref)¶

使用图片、视频、音频作为参考素材引导视频生成。在 prompt 中通过 @ 引用素材。

参数¶

参数	类型	必填	说明
`model`	string	是	模型 ID
`prompt`	string	是	提示词，用 `@image_file_N` / `@video_file_N` / `@audio_file_N` 引用素材
`images`	string[]	否*	参考图片 URL，最多 9 张
`metadata.video_urls`	string[]	否*	参考视频 URL，最多 3 个（总时长 ≤ 15s，每个 ≥ 1.8s）
`metadata.audio_urls`	string[]	否*	参考音频 URL，最多 3 个

* 三者至少提供一种。

@ 引用规则¶

在 prompt 中按以下格式引用素材：

引用格式	对应参数	示例
`@image_file_N`	`images` 第 N 张	`@image_file_1`、`@image_file_2`
`@video_file_N`	`metadata.video_urls` 第 N 个	`@video_file_1`
`@audio_file_N`	`metadata.audio_urls` 第 N 个	`@audio_file_1`

示例¶

图片 + 视频参考音频参考Python（混合引用）

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-official",
    "prompt": "使用 @image_file_1 作为主角，@image_file_2 作为风格参考，@video_file_1 控制节奏",
    "images": [
      "https://example.com/character.png",
      "https://example.com/style.png",
      "https://example.com/extra.png"
    ],
    "duration": 6,
    "metadata": {
      "ratio": "16:9",
      "video_urls": ["https://example.com/ref.mp4"]
    }
  }'

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-official",
    "prompt": "一个人在舞台上随 @audio_file_1 的音乐起舞",
    "images": [
      "https://example.com/ref1.png",
      "https://example.com/ref2.png",
      "https://example.com/ref3.png"
    ],
    "duration": 10,
    "metadata": {
      "ratio": "16:9",
      "audio_urls": ["https://example.com/music.mp3"]
    }
  }'

import requests

resp = requests.post(
    "https://cdn.12ai.org/v1/videos",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2-official",
        "prompt": (
            "使用 @image_file_1 作为主角，@image_file_2 作为风格参考，"
            "@video_file_1 控制节奏，@audio_file_1 作为配音"
        ),
        "images": [
            "https://example.com/character.png",
            "https://example.com/style.png",
            "https://example.com/extra.png",
        ],
        "duration": 6,
        "metadata": {
            "ratio": "16:9",
            "video_urls": ["https://example.com/ref.mp4"],
            "audio_urls": ["https://example.com/ref.mp3"],
        },
    },
)
print(resp.json())

素材过审（Asset Review）¶

默认自动过审

seedance-2-official2-fast 模型已默认开启**自动过审**。直接传公网 URL 即可，系统会在生成前自动完成素材审核流程，无需手动预先上传。

对大多数用户而言，直接使用公网 URL 即可，无需关心素材过审。以下内容仅适用于希望提前管理和复用素材的高级场景。

进阶：复用过审素材¶

如果你希望预先上传一批素材并在多次生成中复用（避免每次重新审核），可以在 资产管理平台 完成上传与管理，然后在生成请求中通过资产 ID 引用。

获取资产 ID¶

访问 asset.12ai.org，使用你的账号登录
创建资产组，上传图片/视频/音频素材
等待审核通过（状态变为 Active）
复制素材的 officialId（格式如 asset-xxxxxxxx）

在生成请求中使用¶

在 images / metadata.video_urls / metadata.audio_urls 中，使用 asset://officialId 格式引用预先过审的素材：

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-official2-fast",
    "prompt": "使用 @image_file_1 作为角色，@video_file_1 控制节奏",
    "images": ["asset://asset-2026character", "asset://asset-2026bg", "asset://asset-2026ref"],
    "duration": 6,
    "size": "720p",
    "metadata": {
      "ratio": "3:4",
      "video_urls": ["asset://asset-2026pace"],
      "audio_urls": ["asset://asset-2026voice"]
    }
  }'

使用限制¶

仅 seedance-2-official2-fast 模型支持 asset:// 引用，seedance-2-official 不支持
素材 ID 格式为 asset://officialId，officialId 在资产管理平台中获取
asset:// 引用可以与普通公网 URL 混用（例如 images 中部分用 URL，部分用 asset://）
素材必须处于 Active 状态才能被引用，Processing（审核中）或 Failed（审核未通过）状态的素材会导致生成失败
素材上传和管理请前往 asset.12ai.org

查询任务状态¶

提交任务后返回 task_id，通过轮询获取结果。

GET /v1/videos/{task_id}

curl https://cdn.12ai.org/v1/videos/task_xxxxxxxxxxxx \
  -H "Authorization: Bearer $API_KEY"

状态流转¶

queued → in_progress → completed
                    ↘ failed

状态	说明	progress
`queued`	已提交，排队等待处理	`0` ~ `20`
`in_progress`	上游正在生成视频	`30`
`completed`	生成成功，`metadata.url` 包含视频链接	`100`
`failed`	生成失败，`error` 包含错误信息	`100`

上游实际状态（processing / succeeded）由系统自动映射为上述标准状态。

响应示例¶

排队 / 处理中已完成失败

{
  "id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2-official",
  "status": "in_progress",
  "progress": 0,
  "created_at": 1775012564
}

生成成功后，视频会自动转存到平台对象存储，metadata.url 返回平台域名链接（不暴露上游地址）。

{
  "id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2-official",
  "status": "completed",
  "progress": 100,
  "created_at": 1775012564,
  "completed_at": 1775012900,
  "metadata": {
    "url": "https://img.12ai.org/videos/task_xxxxxxxxxxxx.mp4"
  }
}

{
  "id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2-official",
  "status": "failed",
  "progress": 100,
  "created_at": 1775012564,
  "error": {
    "message": "content policy violation",
    "code": "content_filter"
  }
}

完整调用示例¶

PythoncURL

import requests
import time

API_BASE = "https://cdn.12ai.org"
API_KEY = "your-api-key"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 1. 创建任务
resp = requests.post(f"{API_BASE}/v1/videos", headers=HEADERS, json={
    "model": "seedance-2-official",
    "prompt": "一只可爱的小猫在阳光下玩耍，柔和的自然阳光，4K",
    "duration": 5,
    "metadata": {
        "ratio": "16:9",
    },
})
task = resp.json()
task_id = task["id"]
print(f"任务已创建: {task_id}")

# 2. 轮询状态
while True:
    resp = requests.get(
        f"{API_BASE}/v1/videos/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    result = resp.json()
    status = result.get("status", "")
    progress = result.get("progress", 0)
    print(f"状态: {status}, 进度: {progress}%")

    if status == "completed":
        video_url = result.get("metadata", {}).get("url", "")
        print(f"生成成功！视频链接: {video_url}")
        break
    elif status == "failed":
        error_msg = result.get("error", {}).get("message", "未知错误")
        print(f"生成失败: {error_msg}")
        break

    time.sleep(5)

# 提交文生视频任务
TASK_ID=$(curl -s -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-official",
    "prompt": "一只可爱的小猫在阳光下玩耍",
    "duration": 5,
    "metadata": {"ratio": "16:9"}
  }' | jq -r '.id')

echo "任务ID: $TASK_ID"

# 轮询状态
while true; do
  RESULT=$(curl -s https://cdn.12ai.org/v1/videos/$TASK_ID \
    -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo $RESULT | jq -r '.status')
  echo "状态: $STATUS"

  if [ "$STATUS" = "completed" ]; then
    echo "视频链接: $(echo $RESULT | jq -r '.metadata.url')"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "失败: $(echo $RESULT | jq -r '.error.message')"
    break
  fi

  sleep 5
done

注意事项¶

图片参数：统一使用 images 数组，系统根据数量自动判断模式
- 0 张 → 文生视频 (text_to_video)
- 1 张 → 图生视频 (image_to_video)
- 2 张 → 首尾帧 (first_last_frame)
- ≥ 3 张 → 多素材参考 (multi_ref)
素材格式：所有素材使用公网可访问的 URL
异步处理：提交成功仅返回任务 ID，通过轮询获取结果
视频转存：生成完成后视频自动转存到平台 R2 对象存储，返回平台域名链接，不暴露上游地址。若 R2 未配置则直接返回上游 URL
视频素材限制：multi_ref 模式下视频最多 3 个，总时长 ≤ 15s，每个 ≥ 1.8s
分辨率：标准版默认 480p，快速版默认 720p，均可通过 size 手动指定
素材过审：seedance-2-official2-fast 默认自动过审，直接传 URL 即可。如需复用过审素材，可前往 asset.12ai.org 管理
计费：按秒计费，最终费用 = 模型单价 × 视频时长（秒）