Seedance 视频生成¶

Sora 兼容接口，支持文生视频、图生视频、视频参考和音频参考。基于即梦（Seedance）模型，提供 5s / 10s / 15s 三种时长选择。

创建视频¶

提交视频生成任务，返回任务 ID 后通过查询接口轮询状态。

POST /v1/videos

Authorizations¶

参数	类型	位置	必填	说明
Authorization	string	header	是	身份验证标头格式为 `Bearer <API_KEY>`，其中 `<API_KEY>` 是您的API令牌。

Body¶

Content-Type: application/json

参数	类型	必填	说明
model	string	是	模型名称，见下方模型列表（模型名已包含时长信息）
prompt	string	是	视频描述提示词，支持 `@N` 引用素材（仅全能参考模式）
filePaths	string[]	否	参考图 URL 列表（仅支持 URL 格式，不支持 Base64）
videoFilePaths	string[]	否	参考视频 URL 列表（单个视频不超过 50MB，最多 3 个）
audioFilePaths	string[]	否	参考音频 URL 列表
ratio	string	否	视频比例，支持 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。是否传 ratio 会影响生成模式，见下方说明

可用模型¶

模型名称	说明
`seedance2-5s`	Seedance 2.0，生成 5 秒视频
`seedance2-10s`	Seedance 2.0，生成 10 秒视频
`seedance2-15s`	Seedance 2.0，生成 15 秒视频

生成模式¶

根据参数组合自动选择不同的生成模式：

模式	条件	说明
文生视频	不传 `filePaths` 和 `videoFilePaths`	纯文本描述生成视频
首帧模式	传 1 张图片，不传 `ratio`	以该图片作为视频首帧生成
首尾帧模式	传 2 张图片，不传 `ratio`	第一张图作为首帧，第二张图作为尾帧
全能参考模式	传图片/视频，且传 `ratio`	素材作为风格/内容参考，支持 `@N` 引用

关键区别

是否传 ratio 决定模式。传了图片不传 ratio = 首帧/首尾帧模式；传了图片且传 ratio = 全能参考模式。

@ 素材引用（仅全能参考模式）¶

在全能参考模式下，可以在 prompt 中使用 @N 引用上传的素材：

编号从 1 开始
图片在前，视频在后：例如传了 2 张图 + 1 个视频，则 @1 @2 引用图片，@3 引用视频
超出素材范围的编号会报错
@ 引用**仅在全能参考模式**（传了 ratio）下生效

素材限制¶

单个视频文件不超过 50MB
最多上传 **3 个**视频
仅支持 URL 格式，不支持 Base64

请求示例¶

文生视频首帧模式首尾帧模式全能参考模式图片+视频混合引用音频参考Python

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

传 1 张图片，不传 ratio，以该图片作为视频首帧：

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

传 2 张图片，不传 ratio，第一张作为首帧，第二张作为尾帧：

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2-5s",
    "prompt": "从白天过渡到夜晚的延时效果",
    "filePaths": ["https://example.com/day.jpg", "https://example.com/night.jpg"]
  }'

传图片/视频，且传 ratio，素材作为风格/内容参考，支持 @N 引用：

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2-5s",
    "prompt": "参考 @1 的风格，生成一段城市夜景延时摄影",
    "filePaths": ["https://example.com/style-ref.jpg"],
    "ratio": "16:9"
  }'

全能参考模式下，图片编号在前，视频编号在后：

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2-10s",
    "prompt": "参考 @1 的角色形象，参考 @2 的运动节奏生成跳舞视频",
    "filePaths": ["https://example.com/character.jpg"],
    "videoFilePaths": ["https://example.com/dance-ref.mp4"],
    "ratio": "16:9"
  }'

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2-5s",
    "prompt": "一个人在舞台上随音乐起舞",
    "audioFilePaths": ["https://example.com/music.mp3"],
    "ratio": "16:9"
  }'

import requests

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

# 文生视频
resp = requests.post(f"{BASE_URL}/v1/videos", headers=HEADERS, json={
    "model": "seedance2-5s",
    "prompt": "电影感特写，温馨木地板上的浅蓝色塑料收纳箱，柔和的自然阳光，4K",
    "ratio": "16:9",
})
print(resp.json())

# 首帧模式（1 张图，不传 ratio）
resp = requests.post(f"{BASE_URL}/v1/videos", headers=HEADERS, json={
    "model": "seedance2-5s",
    "prompt": "让画面中的猫缓缓转头看向镜头",
    "filePaths": ["https://example.com/cat.jpg"],
})
print(resp.json())

# 全能参考模式（传图片 + ratio，使用 @ 引用）
resp = requests.post(f"{BASE_URL}/v1/videos", headers=HEADERS, json={
    "model": "seedance2-5s",
    "prompt": "参考 @1 的风格，生成一段城市夜景延时摄影",
    "filePaths": ["https://example.com/style-ref.jpg"],
    "ratio": "16:9",
})
print(resp.json())

# 图片 + 视频混合引用（全能参考模式）
resp = requests.post(f"{BASE_URL}/v1/videos", headers=HEADERS, json={
    "model": "seedance2-10s",
    "prompt": "参考 @1 的角色形象，参考 @2 的运动节奏生成跳舞视频",
    "filePaths": ["https://example.com/character.jpg"],
    "videoFilePaths": ["https://example.com/dance-ref.mp4"],
    "ratio": "16:9",
})
print(resp.json())

响应示例¶

{
  "id": "vtask_f41f95aab7914476",
  "object": "video",
  "model": "seedance2-5s",
  "status": "queued",
  "progress": 0,
  "created_at": 1770801686
}

查询任务状态¶

查询视频生成任务的当前状态和进度。

GET /v1/videos/{id}

Authorizations¶

参数	类型	位置	必填	说明
Authorization	string	header	是	身份验证标头格式为 `Bearer <API_KEY>`，其中 `<API_KEY>` 是您的API令牌。

Path Parameters¶

参数	类型	必填	说明
id	string	是	创建任务时返回的任务 ID

状态流转¶

queued → in_progress → completed / failed

Response¶

字段	类型	说明
id	string	任务 ID
object	string	固定 `"video"`
model	string	使用的模型
status	string	`queued` / `in_progress` / `completed` / `failed`
progress	integer	进度 0-100
created_at	integer	创建时间戳
video_url	string	视频下载链接（`completed` 时返回）
prompt	string	原始提示词（`completed` 时返回）
completed_at	integer	完成时间戳（`completed` 时返回）
expires_at	integer	过期时间戳（`completed` 时返回，约完成后 24 小时）
error	object/null	错误信息（`failed` 时返回）

请求示例¶

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

响应示例¶

进行中已完成失败

{
  "id": "vtask_f41f95aab7914476",
  "object": "video",
  "model": "seedance2-5s",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1770801686
}

{
  "id": "vtask_f41f95aab7914476",
  "object": "video",
  "model": "seedance2-5s",
  "status": "completed",
  "progress": 100,
  "created_at": 1770801686,
  "prompt": "电影感特写，一只可爱的小猫在阳光下玩耍",
  "completed_at": 1770802030,
  "expires_at": 1770888430,
  "video_url": "https://img.12ai.org/videos/vtask_f41f95aab7914476.mp4",
  "error": null,
  "remixed_from_video_id": null
}

{
  "id": "vtask_f41f95aab7914476",
  "object": "video",
  "model": "seedance2-5s",
  "status": "failed",
  "progress": 0,
  "created_at": 1770801686,
  "error": {
    "message": "你输入的文字描述不符合平台规则，请修改后重试，状态码: 30，错误码: 2047，错误标识: web_fail2generate_input_retry"
  },
  "remixed_from_video_id": null
}

下载视频文件¶

获取已完成视频的 mp4 文件流。这是获取视频的第二种方式，你也可以直接使用查询接口返回的 video_url。

GET /v1/videos/{id}/content

Authorizations¶

参数	类型	位置	必填	说明
Authorization	string	header	是	身份验证标头格式为 `Bearer <API_KEY>`，其中 `<API_KEY>` 是您的API令牌。

Path Parameters¶

参数	类型	必填	说明
id	string	是	任务 ID

Response¶

成功：Content-Type: video/mp4，body 为 mp4 文件流
未完成：409 Conflict，返回错误 JSON
不存在：404 Not Found

请求示例¶

curl -o output.mp4 https://cdn.12ai.org/v1/videos/vtask_f41f95aab7914476/content \
  -H "Authorization: Bearer $API_KEY"

删除任务¶

删除视频生成任务。

DELETE /v1/videos/{id}

Authorizations¶

参数	类型	位置	必填	说明
Authorization	string	header	是	身份验证标头格式为 `Bearer <API_KEY>`，其中 `<API_KEY>` 是您的API令牌。

Path Parameters¶

参数	类型	必填	说明
id	string	是	任务 ID

请求示例¶

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

响应示例¶

成功失败

{
  "message": "Task deleted successfully",
  "success": true
}

{
  "error": {
    "message": "Invalid request, Task not found"
  }
}

调用流程¶

POST /v1/videos              → 拿到任务 ID
        ↓
GET  /v1/videos/{id}          × N（每 3-5 秒轮询，直到 completed / failed）
        ↓
方式一：直接使用响应中的 video_url 下载
方式二：GET /v1/videos/{id}/content 获取文件流

完整调用示例¶

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": "seedance2-5s",
    "prompt": "一只可爱的小猫在阳光下玩耍，柔和的自然阳光，4K",
    "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=HEADERS)
    result = resp.json()
    print(f"状态: {result['status']}  进度: {result['progress']}%")

    if result["status"] == "completed":
        print(f"视频链接: {result['video_url']}")
        break
    elif result["status"] == "failed":
        print(f"失败: {result['error']['message']}")
        break

    time.sleep(5)

# 3. 下载视频（可选，也可直接用 video_url）
resp = requests.get(
    f"{API_BASE}/v1/videos/{task_id}/content", headers=HEADERS
)
with open("output.mp4", "wb") as f:
    f.write(resp.content)
print("视频已保存为 output.mp4")

# 1. 创建任务
TASK_ID=$(curl -s -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance2-5s","prompt":"一只猫在阳光下","ratio":"16:9"}' \
  | jq -r '.id')

echo "任务ID: $TASK_ID"

# 2. 轮询状态
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 $RESULT | jq -r '.video_url'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "失败"
    break
  fi
  sleep 5
done

# 3. 下载视频
curl -o output.mp4 https://cdn.12ai.org/v1/videos/$TASK_ID/content \
  -H "Authorization: Bearer $API_KEY"

错误响应¶

所有错误统一返回以下格式：

{
  "error": {
    "code": 400,
    "message": "错误描述"
  }
}

HTTP 状态码	说明
400	请求参数错误
404	任务不存在
405	请求方法不允许
409	视频未完成（`/content` 接口）
502	服务暂时不可用