SEEDANCE STUDIO
API QUICKSTART

Python API 调用文档

使用 API Key 创建视频任务,查询生成状态,并在完成后下载结果。

Seedance Native JSON共享账户余额与计费HTTPS
01

开始前准备

申请并通过后台审批后,在控制台创建 API Key。完整 Key 只在创建时显示,请妥善保存。

服务地址https://youraisi.com

文档页面会自动使用当前访问域名作为服务地址;部署到其他域名时无需修改示例。API 与网页使用同一账户余额、模型单价和任务计费规则。提交任务会按模型和视频时长预扣费用,明确失败后自动退回。

02

鉴权方式

每次请求都要带 API Key,可使用下面任一请求头。

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY

示例中的 YOUR_API_KEY 只替换为你自己的 Key,不要把 Key 写入公开代码仓库或提交到日志。

03

模型选择

在请求体的 model 字段中填写下表中的完整参数值。该字段必填,共有 6 个选项。

模型与档位model 参数值生成模式分辨率
满血 2.0 · 低速版seedance-2.0-low文生视频、图生视频720p、1080p
满血 2.0 · 高速版seedance-2.0-high文生视频、图生视频720p、1080p
Fast 2.0 · 低速版seedance-2.0-fast-low仅图生视频720p
Fast 2.0 · 高速版seedance-2.0-fast-high仅图生视频720p
Mini 2.0 · 低速版seedance-2.0-mini-low仅图生视频720p
Mini 2.0 · 高速版seedance-2.0-mini-high仅图生视频720p

-low 表示低速档位,-high 表示高速档位;同一模型的两个档位支持相同的生成模式与分辨率。实际完成时间受排队和生成进度影响,价格与可用权限以当前账户配置为准。

只有文字提示词时,选择满血 2.0,并设置 generation_mode: "text-to-video"。使用参考素材时,设置 generation_mode: "image-to-video",至少提供一张参考图片或一个参考视频的 ID;仅有参考音频不能创建图生视频任务。Fast / Mini 必须使用图生视频模式。素材上传方式见下方“上传参考素材”。

旧名称兼容seedance-2.0、seedance-2.0-fast、seedance-2.0-mini 均自动映射到对应的 -high 高速版,并按该档位计费。建议明确填写完整参数值。
04

创建任务

使用 POST /v1/jobs 创建视频任务。每个新任务都必须使用新的幂等键,同一个幂等键只能重放完全相同的请求。

POST/v1/jobs
curl https://youraisi.com/v1/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-001" \
  -d '{
    "model": "seedance-2.0-low",
    "prompt": "一颗红色小球在白色桌面上缓慢滚动",
    "duration_seconds": 5,
    "generation_mode": "text-to-video",
    "resolution": "720p"
  }'
下载 curl 示例
参数类型说明
modelstring必填,完整参数值见上方“模型选择”对照表,例如 seedance-2.0-low 或 seedance-2.0-high
promptstring1 到 5000 个字符的视频生成提示词
duration_secondsinteger视频时长,4 到 15 秒
generation_modestring满血 2.0 支持 text-to-video 和 image-to-video;Fast / Mini 仅支持 image-to-video
resolutionstring720p;满血 2.0 另支持 1080p

Fast 与 Mini 模型必须使用参考图片或参考视频。先调用参考素材上传接口,再在任务参数中传入返回的 ID。materialUrls 不是本服务公开参数,不需要也不建议把素材先上传到公网。

05

上传参考素材

参考素材使用原始二进制请求体上传,不使用 multipart 表单。

POST/v1/reference-media
curl https://youraisi.com/v1/reference-media \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@reference.jpg"

本站不要求素材具备公网 URL;客户端上传后由服务端私有保存,并在生成时通过已认证会话上传到上游,临时地址不会返回。支持 image/jpeg、image/png、image/webp、video/mp4、audio/mpeg、audio/mp4、audio/m4a、audio/x-m4a、audio/wav 及常见 WAV 别名。成功返回 id、media_type、duration_seconds、width、height 和 size_bytes;将返回的 ID 放入 reference_image_ids、reference_video_ids 或 reference_audio_ids。

{
  "id": "REFERENCE_ID",
  "media_type": "image",
  "duration_seconds": null,
  "width": 1920,
  "height": 1080,
  "size_bytes": 245801
}

Fast / Mini 至少需要一张参考图片或一个参考视频;最多 9 张图片、3 个视频和 3 个音频,参考视频总时长不能超过服务端限制。

Python 客户端也可直接调用 upload_media("reference.jpg"),再把返回的 id 放入 reference_image_ids 后创建任务。

06

查询状态

创建成功后保存返回的任务 ID,使用同一 Key 轮询任务。建议间隔 3 到 10 秒。

GET/v1/jobs/{job_id}
curl https://youraisi.com/v1/jobs/JOB_ID \
  -H "X-API-Key: YOUR_API_KEY"

status 可能为 queued、submitting、running、succeeded、failed 或 unknown。progress 提供当前 stage、面向用户的 label、阶段开始时间 since 和已用秒数 elapsed_seconds。

{
  "id": "JOB_ID",
  "status": "running",
  "result_url": null,
  "error": "",
  "attempts": 1,
  "progress": {"stage": "running", "label": "视频生成中", "since": "2026-11-19T12:00:00+00:00", "elapsed_seconds": 42},
  "result_state": "",
  "billing_model": "seedance-2.0-low",
  "billed_yuan": 25.0,
  "billing_status": "reserved",
  "resolution": "720p"
}

结果获取阶段会出现 result_state=pending、downloading、retry_wait 或 ready。任何 status=unknown 都表示结果或提交是否受理尚未明确;不要用新幂等键重复提交。若同时为 result_state=needs_review,请联系管理员核对原上游任务。

07

下载视频

只有 status=succeeded 且 result_state=ready 时才下载。

GET/v1/jobs/{job_id}/content或/v1/jobs/{job_id}/download
curl -L https://youraisi.com/v1/jobs/JOB_ID/download?resolution=720p \
  -H "X-API-Key: YOUR_API_KEY" \
  -o result.mp4

下载接口支持 resolution=720p 或 resolution=1080p。Fast / Mini 仅支持 720P;满血 2.0 可选择 1080P,服务端会在下载前处理固定水印区域,因此 1080P 可能比 720P 更慢。视频缓存过期后,服务端会尝试从原上游任务恢复,不会重新提交生成。

08

Python 示例

项目提供了带可视化 API Key 输入框的完整示例,也可以直接复制下面的核心调用。

import os
import time
from api_client_example import SeedanceClient

client = SeedanceClient(
    base_url=os.getenv("SEEDANCE_API_BASE_URL", "https://youraisi.com"),
    api_key=os.environ["SEEDANCE_API_KEY"],
)

job = client.create_video(
    prompt="A red ball rolls slowly across a white table.",
    model="seedance-2.0-low",
    duration_seconds=5,
    resolution="720p",
)
print("job:", job["id"])

while True:
    current = client.get_job(job["id"])
    progress = current.get("progress") or {}
    print(progress.get("label", current["status"]), progress.get("elapsed_seconds", 0), "s")
    if current["status"] in {"succeeded", "failed"}:
        break
    if current["status"] == "unknown" and current.get("result_state") == "needs_review":
        raise RuntimeError("结果待核对,请联系管理员,不要重复提交")
    time.sleep(5)

if current["status"] == "succeeded":
    client.download_video(job["id"], "result.mp4", resolution=current.get("resolution", "720p"))
下载完整 Python 文件

运行完整文件前安装 Python 3.10 或更高版本。示例不会把 API Key 写入磁盘,建议通过环境变量 SEEDANCE_API_KEY 传入。

09

常见错误

根据 HTTP 状态码和响应中的 detail 判断原因。

状态码含义处理方式
400缺少幂等键或请求头格式错误为每个新任务生成唯一的 Idempotency-Key
401Key 缺失或无效检查请求头,必要时在控制台轮换 Key
402余额不足充值或联系管理员确认额度
409幂等键内容不一致同一幂等键保持请求内容不变,新任务使用新 Key
413 / 415上传体积过大或媒体类型不支持检查文件大小和 Content-Type
422模型、时长、分辨率或参考素材参数无效按本页参数约束修正后再提交
429触发限流或并发限制等待后重试,避免高频提交

人民币余额与按秒计费

费用=模型每秒单价 × 请求的视频时长。10 秒视频按 10 秒计费;提交预扣,成功结算,明确失败自动退款。充值 100 元起。

模型低速版(元/秒)高速版(元/秒)
满血 2.00.100.15
Fast 2.00.060.09
Mini 2.00.040.06

以上为默认价格;客户专属单价由管理员设置,网页和 API 使用同一客户价格。任务结果中的 billed_yuan 表示本次费用,单位为元。账户余额字段为 balance_yuan,模型单价字段为 price_per_second_yuan。

默认输出 720P、9:16,时长 4–15 秒。720P 下载免费,1080P 下载每次收费 0.20 元,失败自动退款。白天高峰期可能排队,22:00 后通常更快。