视频生成接口

按 OpenAI 视频接口格式调用 Seedance 视频生成。视频生成是异步任务：先提交得到任务 ID，再查询进度，完成后下载视频。已经在用火山方舟 SDK 的客户也可以使用火山原生兼容接口。

调用流程#

POST/v1/videos提交生成任务，立即返回任务 ID

GET/v1/videos/{id}查询任务状态与进度，建议每 5–15 秒查询一次

GET/v1/videos/{id}/content任务完成后下载 MP4 视频

状态流转：queued（排队中）→ in_progress（生成中）→ completed（已完成）或 failed（失败）。生成 5 秒视频通常需要 1–3 分钟，高分辨率和长时长会更久。

请在 24 小时内下载

视频完成后下载链接仅保留 24 小时，之后无法再下载。查询结果中的 expires_at（Unix 时间戳，秒）就是下载截止时间，请在此之前下载并保存到你自己的存储中。

提交任务#

POST/v1/videosContent-Type: application/json 或 multipart/form-data

参数	类型	必填	说明
`model`	string	是	模型名，如 `doubao-seedance-2-0-fast-260128`。可用模型及各自能力见模型与能力。
`prompt`	string	文生视频必填	视频描述。可用 `图片1`、`视频1`、`音频1` 按素材在 content 中的顺序引用对应素材（中文写法，不带括号）。
`seconds`	integer	否	视频时长（秒），默认 `5`。Seedance 2.0 系列 4–15，Seedance 2.5 为 4–30；传 `-1` 由模型自动决定时长。也可写作 `duration`。
`resolution`	string	否	`480p` / `720p` / `1080p` / `4k`，默认 `720p`。不同模型支持的档位不同。
`ratio`	string	否	宽高比：`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`，默认 `adaptive`（模型根据内容自动选择）。
`size`	string	否	OpenAI 写法的画面尺寸，如 `1280x720`、`720x1280`，会换算为分辨率和宽高比；同时传了 resolution / ratio 时以它们为准。尺寸必须是支持的尺寸之一。
`generate_audio`	boolean	否	是否自动生成配音，默认 `true`。
`watermark`	boolean	否	是否添加平台水印，默认 `false`。
`seed`	integer	否	随机种子，相同参数和种子可得到相近结果；`-1` 表示随机。
`return_last_frame`	boolean	否	是否额外返回视频最后一帧（PNG），可用于续写下一段视频。尾帧地址通过火山原生兼容接口的 `content.last_frame_url` 获取。
`output_format`	string	否	`mp4`（默认）或 `mov`。
`execution_expires_after`	integer	否	任务排队加生成的最长时间（秒），范围 3600–82800，默认 82800（23 小时）。超时未完成的任务判为失败并全额退款。
`safety_identifier`	string	否	你的终端用户标识（最长 64 字符），用于内容安全追溯，不要填真实个人信息。
`content`	array	否	参考素材列表，用于图生视频、首尾帧、参考视频/音频等，见参考素材。
`image / images`	string / string[]	否	参考图片 URL 的简写，等同于在 content 中添加 `reference_image`。
`input_reference`	file	否	multipart 方式上传一张本地图片（≤ 10 MB）作为参考图，见上传本地图片。
`metadata`	object	否	以上参数也可放在 metadata 中（方便使用 OpenAI SDK 的 extra 参数）。同一参数在两处取值不一致时返回 400。

请求示例cURL

curl https://api-ganfonxai.gangfeng.net/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "清晨的湖面上，一只白鹭缓缓起飞，镜头平稳跟随，写实风格",
    "seconds": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": false
  }'

响应示例200 OK

{
  "id": "task_IOALYFm8XRCFsHrQYzu2A7zWO3puc8Xw",
  "object": "video",
  "model": "doubao-seedance-2-0-fast-260128",
  "status": "queued",
  "progress": 0,
  "created_at": 1792568030
}

参数在提交时即校验，不合规（如模型不支持的分辨率、时长超出范围）会直接返回 400，不会扣费。

参考素材（content）#

content 是一个数组，每个元素通过 type 指定素材类型，role 指定用途：

type	类型	必填	说明
`text`	text	—	文本提示词，多段会按换行拼接。通常直接用顶层 `prompt` 即可。
`image_url`	image_url.url	—	图片。`role`：`first_frame` 首帧、`last_frame` 尾帧、`reference_image` 参考图（默认）。支持公网 HTTP(S) 地址或 `data:image/png;base64,...`。
`video_url`	video_url.url	—	参考视频，`role` 为 `reference_video`。需为公网 HTTP(S) 地址。带参考视频会按「含视频输入」计价，见计费说明。
`audio_url`	audio_url.url	—	参考音频，`role` 为 `reference_audio`。需为公网 HTTP(S) 地址。

最多一张首帧、一张尾帧；使用尾帧时必须同时提供首帧。
各模型可上传的参考图片 / 视频 / 音频数量上限不同，见模型与能力。
Seedance 2.0 系列不能只传音频，必须同时有参考图片或视频；Seedance 2.5 使用首帧时宽高比只能为 adaptive。
素材地址需可被公网访问且在生成期间有效；暂不支持 asset:// 素材库引用。

场景示例#

以下示例均为 POST /v1/videos 的请求体。

首帧图生视频

JSON

{
  "model": "doubao-seedance-2-0-fast-260128",
  "prompt": "图片1 中的女孩睁开眼，温柔地看向镜头，镜头缓缓拉远",
  "seconds": 5,
  "resolution": "720p",
  "content": [
    { "type": "image_url", "role": "first_frame", "image_url": { "url": "https://example.com/girl.png" } }
  ]
}

首尾帧生视频

JSON

{
  "model": "doubao-seedance-2-0-fast-260128",
  "prompt": "从白天过渡到夜晚，城市灯光逐渐亮起",
  "seconds": 5,
  "content": [
    { "type": "image_url", "role": "first_frame", "image_url": { "url": "https://example.com/day.png" } },
    { "type": "image_url", "role": "last_frame",  "image_url": { "url": "https://example.com/night.png" } }
  ]
}

多模态参考（图片 + 视频 + 音频）

JSON

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "以图片1 的产品为主角，参考视频1 的运镜节奏，配合音频1 的背景音乐，做一支 10 秒广告",
  "seconds": 10,
  "resolution": "1080p",
  "ratio": "16:9",
  "content": [
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/product.png" } },
    { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://example.com/camera.mp4" } },
    { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://example.com/bgm.mp3" } }
  ]
}

上传本地图片（multipart）

使用 multipart/form-data，用 input_reference 字段上传一张图片，其余参数作为表单字段；content、metadata 等对象字段需传 JSON 字符串。参考视频和音频仍需使用 URL。

cURL

curl https://api-ganfonxai.gangfeng.net/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -F model=doubao-seedance-2-0-fast-260128 \
  -F prompt="让图片里的猫咪伸个懒腰" \
  -F seconds=5 \
  -F resolution=720p \
  -F input_reference=@./cat.png

查询任务#

GET/v1/videos/{id}

字段	类型	必填	说明
`id`	string	—	任务 ID（`task_` 开头）。
`status`	string	—	`queued` / `in_progress` / `completed` / `failed`。
`progress`	integer	—	进度 0–100，仅供展示参考。
`seconds`	string	—	视频时长（秒）。自动时长的任务在完成后返回实际时长。
`size`	string	—	画面尺寸，如 `1280x720`；自适应宽高比的任务在完成后返回实际尺寸。
`created_at / completed_at`	integer	—	提交时间、完成时间（Unix 时间戳，秒）。
`expires_at`	integer	—	下载截止时间（Unix 时间戳，秒），完成后 24 小时。
`error`	object	—	失败时返回：`code` 为失败类别，`message` 为原因与修改建议。完整列表见错误码。

响应示例

{
  "id": "task_IOALYFm8XRCFsHrQYzu2A7zWO3puc8Xw",
  "object": "video",
  "model": "doubao-seedance-2-0-fast-260128",
  "status": "completed",
  "progress": 100,
  "seconds": "5",
  "size": "1280x720",
  "created_at": 1792568030,
  "completed_at": 1792568136,
  "expires_at": 1792654536
}

失败的任务会自动全额退款，无需申请。

下载视频#

GET/v1/videos/{id}/content返回 video/mp4 文件

任务状态为 completed 后调用，需携带相同的 API Key。下载链接在完成后 24 小时内有效（以 expires_at 为准），请及时下载并保存到你自己的存储。

完整示例#

提交 → 轮询 → 下载的完整流程，将 API_KEY 设为你在控制台创建的密钥。

import os, time, requests

BASE_URL = "https://api-ganfonxai.gangfeng.net"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

# 1. 提交任务
task = requests.post(f"{BASE_URL}/v1/videos", headers=HEADERS, json={
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "清晨的湖面上，一只白鹭缓缓起飞，镜头平稳跟随，写实风格",
    "seconds": 5,
    "resolution": "720p",
    "ratio": "16:9",
}, timeout=60)
task.raise_for_status()
task_id = task.json()["id"]
print("任务已提交:", task_id)

# 2. 每 10 秒查询一次，直到完成或失败
while True:
    time.sleep(10)
    video = requests.get(f"{BASE_URL}/v1/videos/{task_id}", headers=HEADERS, timeout=30).json()
    print("状态:", video["status"], video.get("progress"))
    if video["status"] == "completed":
        break
    if video["status"] == "failed":
        raise SystemExit(f"生成失败: {video['error']['message']}")

# 3. 24 小时内下载并自行保存
content = requests.get(f"{BASE_URL}/v1/videos/{task_id}/content", headers=HEADERS, timeout=300)
content.raise_for_status()
with open(f"{task_id}.mp4", "wb") as file:
    file.write(content.content)
print("已保存:", f"{task_id}.mp4")