Python API 调用文档
使用 API Key 创建视频任务,查询生成状态,并在完成后下载结果。
开始前准备
申请并通过后台审批后,在控制台创建 API Key。完整 Key 只在创建时显示,请妥善保存。
https://youraisi.com文档页面会自动使用当前访问域名作为服务地址;部署到其他域名时无需修改示例。API 与网页使用同一账户余额、模型单价和任务计费规则。提交任务会按模型和视频时长预扣费用,明确失败后自动退回。
鉴权方式
每次请求都要带 API Key,可使用下面任一请求头。
X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY示例中的 YOUR_API_KEY 只替换为你自己的 Key,不要把 Key 写入公开代码仓库或提交到日志。
模型选择
在请求体的 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 高速版,并按该档位计费。建议明确填写完整参数值。创建任务
使用 POST /v1/jobs 创建视频任务。每个新任务都必须使用新的幂等键,同一个幂等键只能重放完全相同的请求。
/v1/jobscurl 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"
}'| 参数 | 类型 | 说明 |
|---|---|---|
model | string | 必填,完整参数值见上方“模型选择”对照表,例如 seedance-2.0-low 或 seedance-2.0-high |
prompt | string | 1 到 5000 个字符的视频生成提示词 |
duration_seconds | integer | 视频时长,4 到 15 秒 |
generation_mode | string | 满血 2.0 支持 text-to-video 和 image-to-video;Fast / Mini 仅支持 image-to-video |
resolution | string | 720p;满血 2.0 另支持 1080p |
Fast 与 Mini 模型必须使用参考图片或参考视频。先调用参考素材上传接口,再在任务参数中传入返回的 ID。materialUrls 不是本服务公开参数,不需要也不建议把素材先上传到公网。
上传参考素材
参考素材使用原始二进制请求体上传,不使用 multipart 表单。
/v1/reference-mediacurl 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 后创建任务。
查询状态
创建成功后保存返回的任务 ID,使用同一 Key 轮询任务。建议间隔 3 到 10 秒。
/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,请联系管理员核对原上游任务。
下载视频
只有 status=succeeded 且 result_state=ready 时才下载。
/v1/jobs/{job_id}/content或/v1/jobs/{job_id}/downloadcurl -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 更慢。视频缓存过期后,服务端会尝试从原上游任务恢复,不会重新提交生成。
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 3.10 或更高版本。示例不会把 API Key 写入磁盘,建议通过环境变量 SEEDANCE_API_KEY 传入。
常见错误
根据 HTTP 状态码和响应中的 detail 判断原因。
| 状态码 | 含义 | 处理方式 |
|---|---|---|
400 | 缺少幂等键或请求头格式错误 | 为每个新任务生成唯一的 Idempotency-Key |
401 | Key 缺失或无效 | 检查请求头,必要时在控制台轮换 Key |
402 | 余额不足 | 充值或联系管理员确认额度 |
409 | 幂等键内容不一致 | 同一幂等键保持请求内容不变,新任务使用新 Key |
413 / 415 | 上传体积过大或媒体类型不支持 | 检查文件大小和 Content-Type |
422 | 模型、时长、分辨率或参考素材参数无效 | 按本页参数约束修正后再提交 |
429 | 触发限流或并发限制 | 等待后重试,避免高频提交 |
人民币余额与按秒计费
费用=模型每秒单价 × 请求的视频时长。10 秒视频按 10 秒计费;提交预扣,成功结算,明确失败自动退款。充值 100 元起。
| 模型 | 低速版(元/秒) | 高速版(元/秒) |
|---|---|---|
| 满血 2.0 | 0.10 | 0.15 |
| Fast 2.0 | 0.06 | 0.09 |
| Mini 2.0 | 0.04 | 0.06 |
以上为默认价格;客户专属单价由管理员设置,网页和 API 使用同一客户价格。任务结果中的 billed_yuan 表示本次费用,单位为元。账户余额字段为 balance_yuan,模型单价字段为 price_per_second_yuan。
默认输出 720P、9:16,时长 4–15 秒。720P 下载免费,1080P 下载每次收费 0.20 元,失败自动退款。白天高峰期可能排队,22:00 后通常更快。