Seedance 2.5，
接入您的产品。

用几次请求，生成第一个视频。

将密钥保存为服务端环境变量 SEADANCE_API_KEY。为本次视频设置唯一的 SEADANCE_REQUEST_KEY（可用 uuidgen 生成），重试时保留此值，并确保账户积分充足。下面示例将预扣 350 积分，生成一个 5 秒 720p 视频。保存响应中的 id，以便查询生成结果。

export SEADANCE_API_KEY="sd_live_your_key"
# Keep this value for retries; choose a new value for a new video.
export SEADANCE_REQUEST_KEY="${SEADANCE_REQUEST_KEY:-$(uuidgen)}"

curl --fail-with-body "https://seedance3ai.dev/api/v1/videos" \
  -H "Authorization: Bearer $SEADANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SEADANCE_REQUEST_KEY" \
  --data '{
  "model": "seedance-2.5",
  "mode": "text-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

本文档不会自动发起生成；发送创建请求会使用您的账户积分。

在服务端完成身份验证。

每次 API 调用都需携带 Authorization: Bearer sd_live_…。不要将密钥放入浏览器、移动端、公开仓库或前端代码。完整密钥仅展示一次，可随时在 API 控制台撤销。

默认密钥权限：videos:write 用于上传和生成；videos:read 用于模型信息与任务查询；account:read 用于积分查询。账户的访问开关和限额对所有密钥共同生效。

创建视频任务。

使用 Content-Type: application/json，为每次计划生成提供唯一 Idempotency-Key。服务端接收上游任务可能需要一些时间；连接超时后，请使用相同请求体和相同幂等键重试。HTTP 202 表示任务已接收，不代表视频已生成。Idempotency-Key 长度为 1–128 个可打印 ASCII 字符，不含空格。

这些字段支持文生视频、首尾帧、多模态参考、视频编辑和延长。当前可用能力和价格以 GET /models 返回结果为准。

{
  "model": "seedance-2.5",
  "mode": "image-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "firstFrameUrl": "YOUR_UPLOADED_PUBLIC_OBJECT_URL"
}

{
  "model": "seedance-2.5",
  "mode": "reference-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "referenceImageUrls": [
    "YOUR_UPLOADED_IMAGE_URL"
  ],
  "referenceVideoUrls": [
    "YOUR_UPLOADED_VIDEO_URL"
  ]
}

先上传，再通过 URL 使用素材。

向 POST /uploads 提交 fileName、contentType、size（字节数）和 kind（image、video 或 audio），在 expiresAt 前按 requiredHeaders 将原始文件通过 PUT 上传到 uploadUrl。上传成功后，在生成请求中使用 publicObjectUrl。素材必须属于当前账户，不接受任意外部 URL 或 base64 输入。

// Node.js 20+ · upload once, then use publicObjectUrl
import { readFile } from "node:fs/promises";

const bytes = await readFile("./first-frame.jpg");
const signed = await fetch("https://seedance3ai.dev/api/v1/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SEADANCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fileName: "first-frame.jpg", contentType: "image/jpeg",
    size: bytes.length, kind: "image",
  }),
});
const upload = await signed.json();
if (!signed.ok) throw new Error(JSON.stringify(upload));
const stored = await fetch(upload.uploadUrl, {
  method: "PUT", headers: upload.requiredHeaders, body: bytes,
});
if (!stored.ok) throw new Error("Upload failed");
console.log(upload.publicObjectUrl);
// Use this URL as firstFrameUrl in an image-to-video request.

申报的文件大小与类型必须和实际上传内容一致。上传地址过期后需重新申请。生成前会校验素材时长、尺寸和格式。

查询任务，直到生成完成。

通过 GET /videos/:id 获取任务状态。建议每 5–10 秒查询一次，遇到 succeeded 或 failed 时停止；如有 Retry-After，请按提示延迟重试。只能查询当前账户通过 API 创建的任务。当前对接方式为轮询。

curl --fail-with-body "https://seedance3ai.dev/api/v1/videos/TASK_ID" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

{
  "id": "a1b2c3d4-1234-4567-8901-abcdef123456",
  "status": "succeeded",
  "credits_reserved": 350,
  "created_at": "2026-10-27T00:00:00.000Z",
  "output": {
    "url": "https://your-result-host.example/video.mp4"
  },
  "error": null,
  "refund_status": "not_applicable"
}

视频生成前 output 为 null；任务失败时返回 error，并通过 refund_status 查看积分退还状态。成功后请及时下载结果。删除视频不会重置生成请求：重放原幂等键（Idempotency-Key）将返回 410 video_deleted，不会再次生成。

接入前，先了解积分费用。

API 生成与网站共用账户积分和 Seedance 2.5 单价。请求被接收时预扣积分，生成失败后退回一次性积分余额；任务创建前的参数校验失败不会生成计费视频。

费用 = 输出时长 × 输出单价 + 参考视频时长 × 参考单价。参考视频由服务端测量，总时长向下取整至秒计费。原生音频已包含在内。例如，5 秒 720p 视频需要 350 积分；若再使用 5 秒参考视频，则需要 600 积分。

curl --fail-with-body "https://seedance3ai.dev/api/v1/models" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

curl --fail-with-body "https://seedance3ai.dev/api/v1/credits" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

API 控制台可查看余额、调用记录和账户限额。请使用同一个账户通过网站价格页补充积分，没有独立的 API 余额或 API 充值接口。可用积分充足即可调用，无需额外订阅。订阅到期和一次性积分规则与网站使用保持一致。

补充积分不会提高 API 请求频率、并发数或每日额度，也不会自动恢复已停用的账户。每日额度按累计预扣积分计算，失败退款不会恢复当日额度，于 UTC 00:00 重置。如需提高限额，请联系支持。

安全重试，避免重复计费。

每个计划生成的视频使用一个 Idempotency-Key，结果明确前请一直保留它与原始请求体。新的幂等键代表新的生成请求。错误响应包含 error.code、error.message 和 request_id；联系支持时请提供请求 ID。