概述
Seedance 2.0 API 提供无审查 AI 视频生成的程序化接口。通过该接口,您可以:
- 上传素材 — 将图片或视频文件上传至云存储作为参考素材
- 生成视频 — 基于文本描述、参考图片或参考视频生成 AI 视频
- 跟踪进度 — 轮询任务状态,获取生成结果 URL
典型流程
1上传素材(可选)→2提交生成任务→3轮询任务状态→4获取视频 URL
认证方式
所有 API 请求必须在 HTTP Header 中携带 API Key 进行身份认证。
Header 格式
http
X-API-Key: <your_api_key>API Key 规则
| 格式 | 由管理员提供的字符串 |
| 获取方式 | 联系管理员开通并获取 |
请求示例
bash
curl https://api.seedance2.movie/api/v1/video/balance \
-H "X-API-Key: <your_api_key>"请妥善保管您的 API Key,不要将其暴露在前端代码或公开仓库中。
通用说明
Base URL
url
https://api.seedance2.movie请求格式
- • Content-Type: application/json
- • 字符编码: UTF-8
- • HTTP 方法: 各接口单独指定
响应格式
所有接口返回统一的 JSON 结构:
成功响应
json
{
"code": "200",
"message": "Success",
"result": {
"...": "..."
}
}错误响应
json
{
"code": "INVALID_PARAMETER",
"message": "Invalid parameter: duration must be 4-15"
}响应字段
| Field | Type | Description |
|---|---|---|
| code | string | 状态码,"200" 表示成功,其他值表示具体错误 |
| message | string | 状态描述,成功时为 "Success" |
| result | object | null | 业务数据,错误时可能为 null |
文件上传
在提交生成任务前,如果需要使用参考图片或参考视频,需先通过预签名接口获取上传地址,再使用 HTTP PUT 将文件上传至云存储。
获取预签名上传地址
POST
/api/v1/video/upload/presign查询参数
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| filename | string | 是 | — | 文件名(最大 128 字符) |
| content_type | string | 是 | — | 文件的 MIME 类型 |
允许的 Content Type
| image/png — .png |
| image/jpeg — .jpg, .jpeg |
| image/webp — .webp |
| video/mp4 — .mp4 |
| video/quicktime — .mov |
| video/webm — .webm |
成功响应
json
{
"code": "200",
"message": "Success",
"result": {
"presigned_url": "https://s3.amazonaws.com/bucket/api/uploads/1/uuid_scene.png?X-Amz-...",
"file_path": "api/uploads/1/uuid_scene.png",
"expires_in": 3600
}
}| Field | Description |
|---|---|
| presigned_url | 预签名上传地址(有效期有限,请尽快使用) |
| file_path | 文件在云存储中的唯一标识 — 提交任务时需要引用此值 |
| expires_in | URL 过期时间(秒) |
上传文件
获取预签名地址后,使用 HTTP PUT 直接上传文件:
bash
curl -X PUT "<presigned_url>" \
-H "Content-Type: image/png" \
--data-binary @./scene.png- • 上传时的 Content-Type 须与获取预签名时的 content_type 一致
- • 预签名地址有效期有限,获取后请尽快上传
- • 上传完成后,使用返回的 file_path 在生成任务中引用该文件
提交视频生成任务
POST
/api/v1/video/task请求体(JSON)
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | 否 | seedance-2.0 | 模型选择 |
| content | array | 是 | — | 输入内容数组(至少 1 项) |
| resolution | string | 否 | 720p | 视频分辨率 |
| ratio | string | 否 | 16:9 | 画面比例 |
| duration | integer | 否 | 5 | 视频时长,单位秒(4–15) |
| generate_audio | boolean | 否 | false | 是否生成音频 |
| seed | integer | 否 | — | 随机种子(-1 或以上,可选) |
| watermark | boolean | 否 | false | 是否添加水印 |
| callback_url | string | 否 | — | 任务完成回调 URL(最大 512 字符) |
| return_last_frame | boolean | 否 | false | 是否返回最后一帧图片 |
模型选项
- • seedance-2.0 — 标准模型(默认)
- • seedance-2.0-fast — 快速模型
分辨率选项
- • 480p
- • 720p(默认)
- • 1080p
画面比例选项
16:99:164:33:41:121:9
内容类型
content 数组中每个元素必须包含 type 字段:
- •
text— 文本提示词,描述视频内容 - •
image_url— 参考图片(使用上传返回的 file_path) - •
video_url— 参考视频(使用上传返回的 file_path) - •
audio_url— 参考音频 - •
sample_id— 示例 ID
bash
curl -X POST https://api.seedance2.movie/api/v1/video/task \
-H "X-API-Key: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0",
"content": [
{ "type": "text", "text": "A cat running under cherry blossoms, warm sunlight" }
],
"resolution": "720p",
"ratio": "16:9",
"duration": 8,
"generate_audio": false
}'成功响应
json
{
"code": "200",
"message": "Success",
"result": {
"task_id": "a1b2c3d4e5f6...",
"status": "pending",
"credit_cost": 14.4
}
}查询任务状态
GET
/api/v1/video/task/{task_id}路径参数
| task_id | 提交任务时返回的任务 ID |
bash
curl https://api.seedance2.movie/api/v1/video/task/a1b2c3d4e5f6 \
-H "X-API-Key: <your_api_key>"成功响应
json
{
"code": "200",
"message": "Success",
"result": {
"task_id": "a1b2c3d4e5f6...",
"model": "seedance-2.0",
"status": "completed",
"resolution": "720p",
"ratio": "16:9",
"duration": 8,
"generate_audio": false,
"seed": null,
"video_url": "https://cdn.example.com/video.mp4?token=...",
"last_frame_url": null,
"error_code": null,
"error_message": null,
"credit_cost": 14.4,
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:33:45Z"
}
}| Field | Description |
|---|---|
| task_id | 任务 ID |
| model | 使用的模型 |
| status | 任务状态(见下方状态表) |
| resolution | 视频分辨率 |
| ratio | 画面比例 |
| duration | 视频时长(秒) |
| generate_audio | 是否生成了音频 |
| seed | 使用的随机种子 |
| video_url | 生成视频的下载地址(成功时返回,签名有效期 7 天) |
| last_frame_url | 最后一帧图片地址(如请求时启用) |
| error_code | 错误码(失败时返回) |
| error_message | 错误描述(失败时返回) |
| credit_cost | 消耗积分 |
| created_at | 任务创建时间(ISO 8601) |
| updated_at | 最后更新时间(ISO 8601) |
任务状态
| pending — 等待处理(非终态) |
| queued — 排队中(非终态) |
| processing — 视频生成中(非终态) |
| completed — 生成成功(终态) |
| failed — 生成失败(终态) |
| cancelled — 已取消(终态) |
| expired — 已过期(终态) |
轮询建议
- • 建议轮询间隔:5–10 秒
- • 当 status 为 completed、failed、cancelled 或 expired 时停止轮询
- • 生成时间通常在 1–5 分钟,视时长和分辨率而定
任务列表
GET
/api/v1/video/tasks分页查询当前 API Key 的所有任务。
查询参数
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| page | integer | 否 | 1 | 页码(从 1 开始,默认: 1) |
| page_size | integer | 否 | 20 | 每页数量(1–100,默认: 20) |
| status | string | 否 | — | 按任务状态筛选(可选) |
bash
curl "https://api.seedance2.movie/api/v1/video/tasks?page=1&page_size=10" \
-H "X-API-Key: <your_api_key>"成功响应
json
{
"code": "200",
"message": "Success",
"result": {
"data": [
"{ ... task objects ... }"
],
"total": 42,
"page": 1,
"page_size": 10
}
}取消任务
POST
/api/v1/video/task/{task_id}/cancel取消处于非终态的任务。pending 状态的任务可以立即取消。queued 或 processing 状态的任务将尝试向供应商发起取消。
bash
curl -X POST https://api.seedance2.movie/api/v1/video/task/a1b2c3d4e5f6/cancel \
-H "X-API-Key: <your_api_key>"成功响应
json
{
"code": "200",
"message": "Success",
"result": {
"task_id": "a1b2c3d4e5f6...",
"status": "cancelled"
}
}处于终态(completed、failed、cancelled、expired)的任务无法取消,将返回 TASK_CANCEL_NOT_ALLOWED 错误。
余额查询
GET
/api/v1/video/balance查询当前 API Key 关联账户的积分余额。
bash
curl https://api.seedance2.movie/api/v1/video/balance \
-H "X-API-Key: <your_api_key>"成功响应
json
{
"code": "200",
"message": "Success",
"result": {
"total_credits": 10000,
"used_credits": 3250.5,
"remain_credits": 6749.5
}
}| Field | Description |
|---|---|
| total_credits | 账户总积分 |
| used_credits | 已消耗积分 |
| remain_credits | 剩余可用积分 |
计费说明
计费模式
API 采用后付费模式:任务成功完成后才扣除积分,失败的任务不扣费。
text
费用 = 每秒单价 × 时长每秒单价(积分)
| 模型 | 分辨率 | 每秒单价 | 示例(8秒) |
|---|---|---|---|
| seedance-2.0 | 1080p | 4.5 | 36.0 |
| seedance-2.0 | 720p | 1.8 | 14.4 |
| seedance-2.0 | 480p | 0.9 | 7.2 |
| seedance-2.0-fast | 1080p | 3.312 | 26.50 |
| seedance-2.0-fast | 720p | 1.44 | 11.52 |
| seedance-2.0-fast | 480p | 0.72 | 5.76 |
示例列显示 8 秒视频的费用:每秒单价 × 8。
充值请联系管理员。
错误码
业务错误码
| Code | Description |
|---|---|
| INVALID_API_KEY | API Key 无效或已禁用 |
| INVALID_PARAMETER | 参数值无效或格式不正确 |
| MISSING_PARAMETER | 缺少必填参数 |
| INSUFFICIENT_CREDIT | 积分余额不足 |
| CREDIT_DEDUCT_FAILED | 积分扣除失败,请重试 |
| TASK_NOT_FOUND | 任务不存在或不属于当前 API Key |
| TASK_SUBMIT_FAILED | 任务提交失败,请重试 |
| TASK_CANCEL_NOT_ALLOWED | 当前状态的任务不允许取消 |
| CONCURRENCY_LIMIT_REACHED | 已达最大并发数,任务已排队 |
| FILE_UPLOAD_FAILED | 生成上传地址失败 |
| VIDEO_DOWNLOAD_FAILED | 视频处理失败 |
| CONTENT_MODERATION_FAILED | 内容审核未通过 — 输入或输出包含敏感内容 |
| COPYRIGHT_VIOLATION | 内容可能涉及版权限制 |
| PRIVACY_VIOLATION | 输入包含真实人物图像,不被允许 |
| SERVICE_BUSY | 服务暂时繁忙,请稍后重试 |
| RATE_LIMIT_EXCEEDED | 请求频率超限,请降低频率 |
| INTERNAL_ERROR | 服务器内部错误 |
HTTP 状态码映射
大部分响应使用 HTTP 200 并在 body 中返回错误详情,但以下 HTTP 状态码也可能返回:
- • 401 — API Key 无效
- • 400 — 参数无效、参数缺失、内容审核或取消不允许
- • 402 — 积分不足
- • 404 — 任务不存在
- • 429 — 频率限制或并发限制
- • 500 — 服务器内部错误或提交失败
- • 503 — 服务繁忙
代码示例
图片生成视频(Python)
上传图片并生成视频:
python
import requests
import time
API_BASE = "https://api.seedance2.movie"
API_KEY = "<your_api_key>"
HEADERS = {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
}
def upload_file(file_path, file_name, content_type):
"""Step 1: Get presigned URL and upload file"""
resp = requests.post(
f"{API_BASE}/api/v1/video/upload/presign",
headers=HEADERS,
params={"filename": file_name, "content_type": content_type},
)
resp.raise_for_status()
data = resp.json()["result"]
# Upload file to presigned URL
with open(file_path, "rb") as f:
requests.put(
data["presigned_url"],
headers={"Content-Type": content_type},
data=f,
).raise_for_status()
print(f"Uploaded: {data['file_path']}")
return data["file_path"]
def submit_task(file_path):
"""Step 2: Submit image-to-video task"""
resp = requests.post(
f"{API_BASE}/api/v1/video/task",
headers=HEADERS,
json={
"model": "seedance-2.0",
"content": [
{"type": "image_url", "image_url": file_path},
{"type": "text", "text": "The character slowly turns around, wind blowing through hair"},
],
"resolution": "720p",
"ratio": "16:9",
"duration": 8,
},
)
resp.raise_for_status()
result = resp.json()["result"]
print(f"Task submitted: {result['task_id']}")
return result["task_id"]
def poll_task(task_id, interval=5, timeout=600):
"""Step 3: Poll task status"""
elapsed = 0
while elapsed < timeout:
resp = requests.get(
f"{API_BASE}/api/v1/video/task/{task_id}",
headers=HEADERS,
)
task = resp.json()["result"]
print(f"[{elapsed}s] Status: {task['status']}")
if task["status"] == "completed":
print(f"Video URL: {task['video_url']}")
return task
if task["status"] in ("failed", "cancelled", "expired"):
print(f"Failed: {task.get('error_message', 'Unknown error')}")
return task
time.sleep(interval)
elapsed += interval
print("Polling timeout")
return None
if __name__ == "__main__":
path = upload_file("./character.png", "character.png", "image/png")
task_id = submit_task(path)
poll_task(task_id)文本生成视频(Python)
无需上传素材,直接通过文本提示词生成视频:
python
import requests
import time
API_BASE = "https://api.seedance2.movie"
HEADERS = {
"X-API-Key": "<your_api_key>",
"Content-Type": "application/json",
}
# Submit text-to-video task
resp = requests.post(
f"{API_BASE}/api/v1/video/task",
headers=HEADERS,
json={
"model": "seedance-2.0",
"content": [
{"type": "text", "text": "A spaceship gliding past Saturn's rings, epic cinematic shot"}
],
"resolution": "720p",
"ratio": "21:9",
"duration": 10,
"generate_audio": True,
},
)
task_id = resp.json()["result"]["task_id"]
print(f"Task submitted: {task_id}")
# Poll until complete
while True:
resp = requests.get(
f"{API_BASE}/api/v1/video/task/{task_id}",
headers=HEADERS,
)
task = resp.json()["result"]
print(f"Status: {task['status']}")
if task["status"] == "completed":
print(f"Video URL: {task['video_url']}")
break
elif task["status"] in ("failed", "cancelled", "expired"):
print(f"Error: {task.get('error_message')}")
break
time.sleep(8)完整流程(cURL)
使用 cURL 逐步调用 API:
bash
# Step 1: Get presigned upload URL
curl -X POST "https://api.seedance2.movie/api/v1/video/upload/presign?filename=scene.png&content_type=image/png" \
-H "X-API-Key: <your_api_key>"
# Step 2: Upload file (use presigned_url from step 1)
curl -X PUT "<presigned_url>" \
-H "Content-Type: image/png" \
--data-binary @./scene.png
# Step 3: Submit generation task (use file_path from step 1)
curl -X POST "https://api.seedance2.movie/api/v1/video/task" \
-H "X-API-Key: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"content": [
{"type": "image_url", "image_url": "<file_path>"},
{"type": "text", "text": "The scene comes alive, flowers blooming"}
],
"duration": 8,
"ratio": "16:9"
}'
# Step 4: Query task status (use task_id from step 3)
curl "https://api.seedance2.movie/api/v1/video/task/<task_id>" \
-H "X-API-Key: <your_api_key>"