跳到正文

Seedance 2.0 FastAPI 参考

用代码调用 Seedance 2.0 Fast 需要的一切:三步快速开始、每个字段和限制、计费公式、回调和幂等。MCP 工具走的也是这套 /v1 接口;通过 MCP 登录时花创作余额,用 API Key 时花开发者 API 余额。

接口POST /v1/videos/generations型号版本dreamina-seedance-2-0-fast-260128OpenAPIllms.txt给 AI 智能体
申请 API 开通

开发者 API 需申请开通。

快速开始三次调用

设置 Key,带价格上限提交任务,再取结果。

  1. 01

    设置 Key

    开发者 API 需申请开通:在创作台的 API Keys 页面申请。Key 只显示一次,存进环境变量。

    Shell
    export API_KEY="sk_test_…"
  2. 02

    提交任务

    带上 Idempotency-Key 和 max_credits 上限(或 quote_id)提交。马上返回 202 和排队中的任务,积分同时冻结。

    POST /videos/generations
    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
    }
  3. 03

    取结果

    轮询这个任务,直到状态是 succeeded。outputs[].url 是签名链接,24 小时后失效,要留的文件及时下载。

    GET /jobs/{id}
    curl https://api.pershot.app/v1/jobs/job_01J9ZK4T8W \
      -H "Authorization: Bearer $API_KEY"

参数和限制

下表读自 OpenAPI 文档,它和接口校验用的是同一套结构定义。不认识的字段会被拒绝。

Seedance 2.0 Fast 请求字段
字段类型取值说明
model必填stringseedance-2.0-fast · seedance-2.0-mini · auto型号 ID。
prompt必填string2–2,000 个字符要生成什么:主体、镜头和光线。
duration默认 5integer4–15输出时长,整数秒,最长 15 秒。
resolution默认 "720p"string480p · 720p输出分辨率。480p 适合出草稿,720p 用于交付;每个分辨率都是单独生成的。
aspect_ratio默认 "16:9"string16:9 · 9:16 · 1:1画幅。
generate_audio默认 trueboolean–原生音频。开不开同价。
image_url可选stringhttps 链接视频的首帧;改图模型的原图。公开的 https 链接或上传得到的链接。
reference_image_urls可选string[]最多 9 个 · https 链接主体和风格的参考图。在提示词里用 @image1、@image2 指代。
seed可选integer0–2,147,483,647接受但忽略:Seedance 2.0 没有种子参数。
quote_id可选string以 qt_ 开头按 POST /v1/quotes 的报价执行,报价 10 分钟内有效。
max_credits可选number> 0这个任务最多花多少。超过就拒绝,不会扣费。
webhook_url可选stringhttps 链接接收任务事件的 https 地址。
end_user_id可选string1–128 个字符仅限已开通的开发者账户(需申请开通):给这次请求标上的你自己的用户 ID,会显示在用量里。
project_id可选string以 prj_ 开头
shot_id可选string以 sht_ 开头
routing_preference可选stringstability · speed
enhance可选object–

quote_id 和 max_credits 必须二选一。这个接口不接受 model 为 "auto":视频请先调用 POST /v1/auto/plan,再带上 max_credits 提交它选出的模型。

频率和并发
默认每个 Key 每分钟 60 次请求,每个账户同时 3 个任务。多开 Key 不会增加并发。

参数限制

下表读自接口校验用的同一张表。每一行都写明由谁检查,超出后会怎样。

  • 平台校验我们检查,不符合就返回 400,不报价也不冻结积分。
  • 供应商校验由供应商检查。被拒的任务会失败,不收费。
  • 建议值没有人检查。控制在范围内,效果更好。
seedance-2.0-fast 的参数限制
限制项取值单位谁来检查超出后
请求参数
提示词长度prompt2 至 2,000字符平台校验返回 400 invalid_request(prompt),不报价,也不冻结积分。
英文提示词prompt最多 1,000单词建议值照常接受。提示词太长,模型可能顾不全。
中文提示词prompt最多 500汉字建议值照常接受。提示词太长,模型可能顾不全。
时长duration4 至 15默认 5秒平台校验返回 400 invalid_request(duration)。只接受整数秒。
分辨率resolution480p, 720p默认 720p–平台校验返回 400 invalid_request(resolution)。
画幅aspect_ratio16:9, 9:16, 1:1默认 16:9–平台校验返回 400 invalid_request(aspect_ratio)。
种子seed忽略–供应商校验接受,但不会发给模型:Seedance 2.0 没有种子参数,同一个种子不能复现结果。
输入视频时长input_video_seconds2 至 15秒平台校验POST /v1/quotes 返回 400 invalid_request。API 的生成接口不接受输入视频。
你传入的图片
参考图reference_image_urls最多 9张平台校验返回 400 invalid_request(reference_image_urls)。
首帧或参考图reference_image_urlsimage_url 或 reference_image_urls,二选一–平台校验返回 400 invalid_request(reference_image_urls)。Seedance 2.0 一个任务只能用其中一种。
图片边长image_urlreference_image_urls300 至 6,000像素(每边)上传图片由平台校验上传的图片:返回 400 invalid_request(image_url 或 reference_image_urls.N),不报价,也不冻结积分。其他链接:供应商拒绝任务,不收费。
图片宽高比image_urlreference_image_urls0.4 至 2.5宽 ÷ 高上传图片由平台校验上传的图片:返回 400 invalid_request(image_url 或 reference_image_urls.N),不报价,也不冻结积分。其他链接:供应商拒绝任务,不收费。
上传大小file最多 10MB平台校验POST /v1/uploads 返回 400 invalid_request(file)。
上传格式fileJPEG, PNG, WebP–平台校验按文件内容判断,不看文件名。其他类型返回 400 invalid_request(file)。
外链图片大小image_urlreference_image_urls最多 30MB供应商校验适用于其他网站上的图片。供应商拒绝任务,不收费。
外链图片格式image_urlreference_image_urlsJPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF–供应商校验适用于其他网站上的图片。供应商拒绝任务,不收费。
输出
输出像素480p16:9864×4969:16496×8641:1640×640720p16:91280×7209:16720×12801:1960×960像素供应商校验由模型按分辨率和画幅决定。
帧率24fps供应商校验所有视频都一样。
输出格式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 × 刊例单价
Seedance 2.0 Fast 价格
规格每秒(API)5 秒10 秒15 秒
480p无视频输入$0.031有视频输入:$0.019/秒≈ 322 秒 / $1016 积分≈ $0.1631 积分≈ $0.3147 积分≈ $0.47
720p无视频输入$0.067有视频输入:$0.040/秒≈ 149 秒 / $1034 积分≈ $0.3467 积分≈ $0.67100 积分≈ $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=…"
        }
      ]
    }
  }
}
校验 X-Signature
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_request400按 param 指出的字段修改。
unauthorized401检查 Key 和 Bearer 请求头。
insufficient_credits402充值后用同一个 Idempotency-Key 重试。
forbidden_model403在创作台把该型号或工具加进这个 Key 的可用清单,或换一个 Key。视频增强等工具要单独勾选。
quote_expired409重新报价,报价 10 分钟内有效。
price_changed409价格超过了你的上限。重新报价,或调高 max_credits。
content_rejected422没有扣费。修改提示词或图片后再试。
rate_limited429按 Retry-After 等待后重试。
upstream_unavailable503模型暂时不可用,稍后重试。没有开始的任务不收费。