Seedance 2.5 按秒视频 API 教程

准备工作

在 BotCF 控制台创建 API Key，确保令牌可使用 🎥视频生成按秒 分组。接口统一使用公开地址：

export BASE_URL="https://botcf.com/v1"
export API_KEY="sk-你的BotCF令牌"

不要把 API Key 写进公开网页、截图或发给他人。

1. 文生视频

向 POST /v1/videos 提交 JSON。下面示例生成 30 秒、720p 横屏视频：

curl --location "$BASE_URL/videos" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedance2.5",
    "prompt": "电影感航拍镜头，清晨云海缓慢掠过雪山，光线自然，镜头运动平稳",
    "seconds": "30",
    "size": "1280x720",
    "resolution_name": "720p",
    "preset": "normal"
  }'

创建成功后会返回任务 ID。后续查询和下载必须保存这个 id：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "seedance2.5",
  "status": "queued",
  "progress": 0,
  "seconds": "30"
}

2. 加入参考图

参考图放在 images 数组中。支持可直接访问的 HTTPS 图片地址，也支持 data:image/...;base64,... 数据地址。画布当前会按顺序使用最多 7 张参考图。

方式 A：使用公网图片地址

curl --location "$BASE_URL/videos" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedance2.5",
    "prompt": "保持参考图中的人物外观和服装，人物转身看向镜头，头发随风轻轻摆动，固定机位",
    "images": [
      "https://example.com/reference-person.jpg"
    ],
    "seconds": "10",
    "size": "720x1280",
    "resolution_name": "720p",
    "preset": "normal"
  }'

图片地址必须直接返回图片文件，不能要求登录，也不能是带访问密码的分享页面。多张参考图继续放进同一个数组：

"images": [
  "https://example.com/person.jpg",
  "https://example.com/clothes.jpg",
  "https://example.com/scene.jpg"
]

方式 B：把本地图片转成 Base64

本地文件不能直接写成电脑路径。先转成数据地址，再放进 images。以下 Python 示例会自动读取 reference.jpg：

import base64
import mimetypes

path = "reference.jpg"
mime = mimetypes.guess_type(path)[0] or "image/jpeg"
with open(path, "rb") as image_file:
    encoded = base64.b64encode(image_file.read()).decode("ascii")

image_data_url = f"data:{mime};base64,{encoded}"
print(image_data_url[:80] + "...")

发送请求时把 image_data_url 作为 images 的一项即可。完整 Python 示例见下文。

3. 查询进度

export TASK_ID="task_替换成创建任务返回的ID"

curl "$BASE_URL/videos/$TASK_ID" \
  --header "Authorization: Bearer $API_KEY"

建议每 10 至 20 秒查询一次，不要高频重复创建任务。

4. 下载 MP4

仅在任务状态为 completed 后调用内容接口：

curl --location "$BASE_URL/videos/$TASK_ID/content" \
  --header "Authorization: Bearer $API_KEY" \
  --output seedance2.5.mp4

Python 完整示例（含本地参考图）

先安装依赖：pip install requests。将参考图保存为 reference.jpg，然后运行：

import base64
import mimetypes
import os
import time

import requests

API_KEY = os.environ["BOTCF_API_KEY"]
BASE_URL = "https://botcf.com/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

image_path = "reference.jpg"
mime = mimetypes.guess_type(image_path)[0] or "image/jpeg"
with open(image_path, "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode("ascii")

create_response = requests.post(
    f"{BASE_URL}/videos",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "model": "seedance2.5",
        "prompt": "保持参考图主体一致，人物缓慢抬头看向远方，电影感自然光，镜头平稳",
        "images": [f"data:{mime};base64,{image_data}"],
        "seconds": "10",
        "size": "1280x720",
        "resolution_name": "720p",
        "preset": "normal",
    },
    timeout=120,
)
create_response.raise_for_status()
task_id = create_response.json()["id"]
print("任务已创建：", task_id)

while True:
    response = requests.get(
        f"{BASE_URL}/videos/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()
    status = task.get("status")
    print(f"状态：{status}，进度：{task.get('progress', 0)}%")

    if status == "completed":
        break
    if status in {"failed", "cancelled", "expired"}:
        error = task.get("error") or {}
        raise RuntimeError(error.get("message", "视频生成失败"))
    time.sleep(15)

with requests.get(
    f"{BASE_URL}/videos/{task_id}/content",
    headers=HEADERS,
    stream=True,
    timeout=300,
) as video_response:
    video_response.raise_for_status()
    with open("seedance2.5.mp4", "wb") as output:
        for chunk in video_response.iter_content(1024 * 1024):
            if chunk:
                output.write(chunk)

print("视频已保存：seedance2.5.mp4")

参数说明

常见问题

返回 401 或 403

检查 API Key 是否完整、是否启用，以及令牌是否允许使用 🎥视频生成按秒 分组。

参考图没有生效

确认 images 是数组；公网 URL 必须能直接下载原图，本地图片必须转成完整的 Base64 数据地址。提示词中也要明确要求保持哪个主体或元素。

任务一直生成中

保持同一个任务 ID 继续查询。视频生成通常需要数分钟，长视频或高峰期会更久，不要因为等待而重复提交同一任务。