Seedance 2.0 FastAPI 参考
用代码调用 Seedance 2.0 Fast 需要的一切:三步快速开始、每个字段和限制、计费公式、回调和幂等。MCP 工具走的也是这套 /v1 接口;通过 MCP 登录时花创作余额,用 API Key 时花开发者 API 余额。
开发者 API 需申请开通。
快速开始三次调用
设置 Key,带价格上限提交任务,再取结果。
- 01
设置 Key
开发者 API 需申请开通:在创作台的 API Keys 页面申请。Key 只显示一次,存进环境变量。
export API_KEY="sk_test_…" - 02
提交任务
带上 Idempotency-Key 和 max_credits 上限(或 quote_id)提交。马上返回 202 和排队中的任务,积分同时冻结。
curl https://api.pershot.app/v1/videos/generations \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance-2.0-fast", "prompt": "Perfume mist in hard side light. Slow push-in, black background, grain.", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9", "generate_audio": true, "max_credits": 34 }'{ "id": "job_01J9ZK4T8W", "object": "job", "kind": "video", "status": "queued", "money_status": "reserved", "queue_position": 2, "requested_model": "seedance-2.0-fast", "credits_quoted": 34, "credits_charged": null } - 03
取结果
轮询这个任务,直到状态是 succeeded。outputs[].url 是签名链接,24 小时后失效,要留的文件及时下载。
curl https://api.pershot.app/v1/jobs/job_01J9ZK4T8W \ -H "Authorization: Bearer $API_KEY"
参数和限制
下表读自 OpenAPI 文档,它和接口校验用的是同一套结构定义。不认识的字段会被拒绝。
| 字段 | 类型 | 取值 | 说明 |
|---|---|---|---|
model必填 | string | seedance-2.0-fast · seedance-2.0-mini · auto | 型号 ID。 |
prompt必填 | string | 2–2,000 个字符 | 要生成什么:主体、镜头和光线。 |
duration默认 5 | integer | 4–15 | 输出时长,整数秒,最长 15 秒。 |
resolution默认 "720p" | string | 480p · 720p | 输出分辨率。480p 适合出草稿,720p 用于交付;每个分辨率都是单独生成的。 |
aspect_ratio默认 "16:9" | string | 16:9 · 9:16 · 1:1 | 画幅。 |
generate_audio默认 true | boolean | – | 原生音频。开不开同价。 |
image_url可选 | string | https 链接 | 视频的首帧;改图模型的原图。公开的 https 链接或上传得到的链接。 |
reference_image_urls可选 | string[] | 最多 9 个 · https 链接 | 主体和风格的参考图。在提示词里用 @image1、@image2 指代。 |
seed可选 | integer | 0–2,147,483,647 | 接受但忽略:Seedance 2.0 没有种子参数。 |
quote_id可选 | string | 以 qt_ 开头 | 按 POST /v1/quotes 的报价执行,报价 10 分钟内有效。 |
max_credits可选 | number | > 0 | 这个任务最多花多少。超过就拒绝,不会扣费。 |
webhook_url可选 | string | https 链接 | 接收任务事件的 https 地址。 |
end_user_id可选 | string | 1–128 个字符 | 仅限已开通的开发者账户(需申请开通):给这次请求标上的你自己的用户 ID,会显示在用量里。 |
project_id可选 | string | 以 prj_ 开头 | |
shot_id可选 | string | 以 sht_ 开头 | |
routing_preference可选 | string | stability · speed | |
enhance可选 | object | – |
quote_id 和 max_credits 必须二选一。这个接口不接受 model 为 "auto":视频请先调用 POST /v1/auto/plan,再带上 max_credits 提交它选出的模型。
- 频率和并发
- 默认每个 Key 每分钟 60 次请求,每个账户同时 3 个任务。多开 Key 不会增加并发。
参数限制
下表读自接口校验用的同一张表。每一行都写明由谁检查,超出后会怎样。
- 平台校验我们检查,不符合就返回 400,不报价也不冻结积分。
- 供应商校验由供应商检查。被拒的任务会失败,不收费。
- 建议值没有人检查。控制在范围内,效果更好。
| 限制项 | 取值 | 单位 | 谁来检查 | 超出后 |
|---|---|---|---|---|
| 请求参数 | ||||
提示词长度prompt | 2 至 2,000 | 字符 | 平台校验 | 返回 400 invalid_request(prompt),不报价,也不冻结积分。 |
英文提示词prompt | 最多 1,000 | 单词 | 建议值 | 照常接受。提示词太长,模型可能顾不全。 |
中文提示词prompt | 最多 500 | 汉字 | 建议值 | 照常接受。提示词太长,模型可能顾不全。 |
时长duration | 4 至 15默认 5 | 秒 | 平台校验 | 返回 400 invalid_request(duration)。只接受整数秒。 |
分辨率resolution | 480p, 720p默认 720p | – | 平台校验 | 返回 400 invalid_request(resolution)。 |
画幅aspect_ratio | 16:9, 9:16, 1:1默认 16:9 | – | 平台校验 | 返回 400 invalid_request(aspect_ratio)。 |
种子seed | 忽略 | – | 供应商校验 | 接受,但不会发给模型:Seedance 2.0 没有种子参数,同一个种子不能复现结果。 |
输入视频时长input_video_seconds | 2 至 15 | 秒 | 平台校验 | POST /v1/quotes 返回 400 invalid_request。API 的生成接口不接受输入视频。 |
| 你传入的图片 | ||||
参考图reference_image_urls | 最多 9 | 张 | 平台校验 | 返回 400 invalid_request(reference_image_urls)。 |
首帧或参考图reference_image_urls | image_url 或 reference_image_urls,二选一 | – | 平台校验 | 返回 400 invalid_request(reference_image_urls)。Seedance 2.0 一个任务只能用其中一种。 |
图片边长image_urlreference_image_urls | 300 至 6,000 | 像素(每边) | 上传图片由平台校验 | 上传的图片:返回 400 invalid_request(image_url 或 reference_image_urls.N),不报价,也不冻结积分。其他链接:供应商拒绝任务,不收费。 |
图片宽高比image_urlreference_image_urls | 0.4 至 2.5 | 宽 ÷ 高 | 上传图片由平台校验 | 上传的图片:返回 400 invalid_request(image_url 或 reference_image_urls.N),不报价,也不冻结积分。其他链接:供应商拒绝任务,不收费。 |
上传大小file | 最多 10 | MB | 平台校验 | POST /v1/uploads 返回 400 invalid_request(file)。 |
上传格式file | JPEG, PNG, WebP | – | 平台校验 | 按文件内容判断,不看文件名。其他类型返回 400 invalid_request(file)。 |
外链图片大小image_urlreference_image_urls | 最多 30 | MB | 供应商校验 | 适用于其他网站上的图片。供应商拒绝任务,不收费。 |
外链图片格式image_urlreference_image_urls | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF | – | 供应商校验 | 适用于其他网站上的图片。供应商拒绝任务,不收费。 |
| 输出 | ||||
| 输出像素 | 480p16:9864×4969:16496×8641:1640×640720p16:91280×7209:16720×12801:1960×960 | 像素 | 供应商校验 | 由模型按分辨率和画幅决定。 |
| 帧率 | 24 | fps | 供应商校验 | 所有视频都一样。 |
| 输出格式 | MP4 | – | 供应商校验 | 视频都是 MP4。开启 generate_audio 时带声音。 |
| 链接 | ||||
| 上传链接 | 7 | 天 | 平台校验 | 过期后链接返回 403,需要重新上传。 |
| 结果链接 | 24 | 小时 | 平台校验 | 过期后链接返回 403。重新读取任务即可拿到新链接。文件本身保留 12 个月(任务的 outputs_expire_at 是具体日期);存进素材库或用在项目里的会保留更久。 |
其他网站上的图片我们不会去下载。这类链接由供应商检查尺寸,被拒的任务不收费。 同样的限制也能以 JSON 读取:GET /v1/models 为每个型号返回 limits 对象。
价格算法公开
每个任务执行前先用积分报价(1 美元 = 100 积分)。每秒价格用于做预算,准确数字以 POST /v1/quotes 的报价为准。
积分 = 向上取整(BytePlus 刊例价 × 0.55 × 100),其中刊例价 =(输入秒数 + 输出秒数)× 宽 × 高 × 24 ÷ 1024 × 刊例单价| 规格 | 每秒(API) | 5 秒 | 10 秒 | 15 秒 |
|---|---|---|---|---|
| 480p无视频输入 | $0.031有视频输入:$0.019/秒≈ 322 秒 / $10 | 16 积分≈ $0.16 | 31 积分≈ $0.31 | 47 积分≈ $0.47 |
| 720p无视频输入 | $0.067有视频输入:$0.040/秒≈ 149 秒 / $10 | 34 积分≈ $0.34 | 67 积分≈ $0.67 | 100 积分≈ $1.00 |
被拒或失败的任务不收费。
回调和幂等
重试不会重复扣费,也不必一直轮询。
- 幂等
- 每个生成请求都要带 Idempotency-Key(1 至 255 个可见 ASCII 字符)。24 小时内用同一个键,返回同一个任务和 HTTP 200,所以超时后重试不会多建任务,也不会多扣费。
- 被拒的提示词
- 预检拒绝的提示词(422 content_rejected)什么都不会创建,同一个键可以换个提示词再用。
- 事件
job.queuedjob.processingjob.succeededjob.failedjob.cancelled- 签名
- X-Signature 里有 t(Unix 时间)和 v1:用你的 whsec_ 密钥,对 t、一个点和原始请求体做 HMAC-SHA256。时间戳超过 5 分钟的请求直接拒绝,并按 X-Event-Id 去重。
- 投递
- 10 秒内返回 2xx 即算送达。失败后依次在 1 分钟、5 分钟、30 分钟、2 小时、6 小时后重试。不跟随重定向。
{
"id": "evt_01J9ZKB1QX",
"type": "job.succeeded",
"created_at": "2026-09-29T14:02:31Z",
"data": {
"job": {
"id": "job_01J9ZK4T8W",
"object": "job",
"kind": "video",
"status": "succeeded",
"money_status": "settled",
"requested_model": "seedance-2.0-fast",
"credits_charged": 34,
"outputs": [
{
"kind": "video",
"url": "https://…/job_01J9ZK4T8W.mp4?sig=…"
}
]
}
}
}import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody: the request body exactly as received, before any JSON parsing.
export function verifyWebhook(header, rawBody, secret, toleranceSec = 300) {
let t = null;
const signatures = [];
for (const item of (header ?? "").split(",")) {
const [key, value] = item.split("=", 2);
if (key === "t") t = Number(value);
if (key === "v1") signatures.push(Buffer.from(value, "hex"));
}
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
return signatures.some((s) => s.length === expected.length && timingSafeEqual(s, expected));
}
// verifyWebhook(req.headers["x-signature"], rawBody, process.env.WEBHOOK_SECRET)
// Answer 2xx quickly, and skip an X-Event-Id you have already handled.错误码和处理办法
所有错误的结构都一样:一个 error 对象,含 code、message、param 和 request_id。最常遇到的是这些:
| 错误码 | HTTP | 怎么处理 |
|---|---|---|
invalid_request | 400 | 按 param 指出的字段修改。 |
unauthorized | 401 | 检查 Key 和 Bearer 请求头。 |
insufficient_credits | 402 | 充值后用同一个 Idempotency-Key 重试。 |
forbidden_model | 403 | 在创作台把该型号或工具加进这个 Key 的可用清单,或换一个 Key。视频增强等工具要单独勾选。 |
quote_expired | 409 | 重新报价,报价 10 分钟内有效。 |
price_changed | 409 | 价格超过了你的上限。重新报价,或调高 max_credits。 |
content_rejected | 422 | 没有扣费。修改提示词或图片后再试。 |
rate_limited | 429 | 按 Retry-After 等待后重试。 |
upstream_unavailable | 503 | 模型暂时不可用,稍后重试。没有开始的任务不收费。 |