Seedance 2.0 API

通过异步任务创建、状态轮询、Webhook 和积分计费，将视频生成功能集成到您的产品中。

创建 API 密钥 API 仪表板

基本 URL

https://api.seedance2.ai

本页内容

简介

API 允许您以编程方式提交 Seedance 2.0 视频生成任务。生成是异步的：创建一个任务，立即收到任务 ID，然后通过轮询任务端点或接收 Webhook 获取完成的视频。

异步任务

轮询适用于开发和简单集成。

Webhook 就绪

建议在生产环境中使用 Webhook，因为它们避免了频繁的轮询，并在任务达到终端状态时通知您的服务。

积分感知

提交时会保留积分。成功完成的任务将从该预留中扣除；失败或超时的任务将自动退款。

认证

在仪表板中创建 API 密钥，并在每个请求中将其作为 Bearer token 发送。完整密钥仅在创建时显示一次。

Authorization: Bearer sk_live_xxxxxxxx

sk_live_

使用 sk_live_ 密钥处理生产流量。

sk_test_

使用 sk_test_ 密钥进行沙盒集成测试，使用相同的 API 契约。

401

缺少、无效或已撤销的密钥将返回 invalid_api_key 及 HTTP 401 错误。

快速开始

首先提交任务。任务被接受后，选择一种结果交付方式：轮询任务端点，或通过 Webhook 接收终端结果。

提交任务

创建异步视频任务并立即接收任务 ID。

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'

结果选项：轮询

当您的集成偏好显式轮询时，获取任务状态端点。

curl https://api.seedance2.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

结果选项：Webhook

提交任务时传递 callback_url，然后接收完成或失败的回调，并更新您自己的任务记录。

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

创建视频任务

使用 POST /v1/videos/generations 创建视频任务。请求体包含一个顶级模型、一个可选的 callback_url 以及一个包含提示和生成设置的 input 对象。

POST

/v1/videos/generations

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'

生成模式

generation_type 控制接受哪些媒体输入以及模型如何解释它们。

模式	所需媒体	可选媒体	备注
`text-to-video`	prompt	duration, aspect_ratio, resolution, seed	仅限文本提示。image_urls、video_urls 和 audio_urls 不需要。
`image-to-video`	prompt + image_urls 数组（1-2 个图片 URL）	duration, aspect_ratio, resolution, seed	image_urls 必须是一个数组。提供 1 个图片 URL 用于第一帧，或 2 个图片 URL 用于第一帧和最后一帧。视频和音频将被忽略。
`reference-to-video`	prompt + 至少一张图片或一个视频	在素材限制内的图片、视频和音频	音频不能单独与文本一起使用。提供音频时，请至少添加一张图片或一个视频。

text-to-video

当提示是唯一的创意输入时，使用文本到视频。 (text-to-video)

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cinematic drone shot over a futuristic coastal city at sunrise",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'

image-to-video

当 input.image_urls 是包含 1-2 个图片 URL 的数组时，使用图片到视频：一个 URL 设置第一帧，两个 URL 设置第一帧和最后一帧。在此模式下，视频和音频引用将被忽略。 (image-to-video)

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "input": {
      "prompt": "the subject turns toward camera, soft studio motion",
      "generation_type": "image-to-video",
      "image_urls": ["https://your.cdn.com/first-frame.jpg"],
      "duration": 5,
      "resolution": "720p"
    }
  }'

reference-to-video

使用参考到视频，通过参考图片、视频和音频获得更丰富的指导。音频不能单独与文本一起使用；提供音频时，请至少包含一张图片或一个视频。 (reference-to-video)

素材限制

最多 9 张参考图片
最多 3 个参考视频，总时长 <= 15 秒
最多 3 个参考音频，总时长 <= 15 秒
所有类型总共最多 12 个素材

支持的输入组合

文本 + 图片

文本 + 视频

文本 + 图片 + 视频

文本 + 图片 + 音频

文本 + 视频 + 音频

文本 + 图片 + 视频 + 音频

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "input": {
      "prompt": "use the product from image 1 and the camera motion from the reference video",
      "generation_type": "reference-to-video",
      "image_urls": ["https://your.cdn.com/product.jpg"],
      "video_urls": ["https://your.cdn.com/camera-motion.mp4"],
      "audio_urls": [],
      "duration": 8,
      "resolution": "1080p"
    }
  }'

请求参数

参数名称、枚举值、端点路径和示例是 API 契约的一部分。以下说明解释了每个字段的行为方式。

请求头

请求头	必填	描述	示例
`Authorization`	是	用于验证请求的 Bearer API 密钥。	`Bearer sk_live_xxx`
`Content-Type`	是	所有写入请求都使用 JSON。	`application/json`

顶级字段

字段	类型	必填	默认	范围 / 枚举	模式	示例
`model` 用于生成的模型变体。	string	是	-	seedance-2-0 \| seedance-2-0-fast	全部	`seedance-2-0`
`callback_url` 接收任务完成和失败回调的 HTTPS 端点。	string	否	-	HTTPS URL，非私有网络	全部	`https://your-domain.com/hook`
`input` 生成设置和媒体参考。	object	是	-	-	全部	`-`

`input.*` 字段

字段	类型	必填	默认	范围 / 枚举	模式	示例
`input.prompt` 描述要创建视频的文本提示。	string	是	-	非空文本	全部	`a cat surfing`
`input.generation_type` 生成模式。默认为文本到视频。 (text-to-video)	string	否	text-to-video	text-to-video \| image-to-video \| reference-to-video	-	`image-to-video`
`input.image_urls` 可公开访问的图片 URL。对于图片到视频，发送 1 张图片用于第一帧，或 2 张图片用于第一帧和最后一帧。对于参考到视频，最多发送 9 张图片作为视觉参考。 (image-to-video) (reference-to-video)	string[]	有条件的	[]	图片到视频: 1 或 2 张图片。参考到视频: 最多 9 张图片。 (image-to-video) (reference-to-video)	image-to-video / reference-to-video	`["https://.../a.jpg"]`
`input.video_urls` 仅用于参考到视频的可公开访问的参考视频。您最多可以发送 3 个视频文件，其总播放时间必须小于或等于 15 秒。 (reference-to-video)	string[]	否	[]	最多 3 个视频。视频总长度必须小于或等于 15 秒。	reference-to-video	`[]`
`input.audio_urls` 仅用于参考到视频的可公开访问的参考音频文件。您最多可以发送 3 个音频文件，其总播放时间必须小于或等于 15 秒。 (reference-to-video)	string[]	否	[]	最多 3 个音频文件。音频总长度必须小于或等于 15 秒。	reference-to-video	`[]`
`input.duration` 输出视频的长度（秒）。	int	否	5	4-15 秒	全部	`5`
`input.aspect_ratio` 输出宽高比。adaptive 允许服务推断最佳宽高比。	string	否	adaptive	16:9 \| 4:3 \| 1:1 \| 3:4 \| 9:16 \| 21:9 \| adaptive	全部	`16:9`
`input.resolution` 输出分辨率层级。	string	否	720p	480p \| 720p \| 1080p	全部	`720p`
`input.generate_audio` 当支持时，模型是否应该生成音频。	boolean	否	true	true \| false	全部	`true`
`input.watermark` 是否添加水印。	boolean	否	false	true \| false	全部	`false`
`input.web_search` 当支持时，是否允许网络搜索增强。	boolean	否	false	true \| false	全部	`false`
`input.return_last_frame` 当可用时，是否返回最后一帧的 URL。	boolean	否	false	true \| false	全部	`false`
`input.seed` 确定性种子。使用 -1 表示随机种子。	int	否	-1	-1 或 0-4294967295	全部	`-1`

积分消耗因分辨率、时长、模型以及参考到视频是否包含视频参考而异。创建响应返回的积分值是该任务实际保留的金额。 (reference-to-video)

查看积分定价

响应

这是 POST /v1/videos/generations 的成功响应。这意味着任务已被接受且积分已被保留。使用返回的 taskId 轮询 GET /v1/tasks/:id 或匹配完成或失败回调。

POST /v1/videos/generations 成功响应

{
  "taskId": "3f2aK9mR...",
  "credits": 60
}

获取任务状态

使用 GET /v1/tasks/:id 获取当前任务状态。轮询间隔不得少于 10 秒。对于生产系统，建议使用 Webhook。

curl https://api.seedance2.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

已完成任务响应

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "billing_status": "charged",
  "credits": 60,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seedance2.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

失败任务响应

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "billing_status": "refunded",
  "credits": 60,
  "failed_reason": "provider_failed"
}

值	含义
`status=queued`	已接受，等待提交或处理。
`status=generating`	提供商正在处理生成。
`status=completed`	视频已完成，data.results 包含结果 URL。
`status=failed`	生成失败或超时。
`billing_status=reserved`	任务进行中时，积分已保留。
`billing_status=charged`	任务成功，预留已结算。
`billing_status=refunded`	任务失败或超时，积分已退还。
`billing_status=refund_failed`	退款交易失败，需要手动处理。

在 video_expires_at 之后，data.results 为空。请在有效期结束前下载并存储文件。

Webhook

当存在 callback_url 时，当任务完成或失败时，Seedance 将调用您的端点，并发送描述最终结果的 JSON 数据。如果您的端点返回非 2xx 响应或在 15 秒内未响应，则会重试最多 5 次投递。重试会重复使用相同的任务 ID，因此请按 ID 进行去重。一旦安全地记录了回调数据，请尽快返回 200 响应。

任务完成回调

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "data": {
    "results": ["https://cdn.seedance2.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

任务失败回调

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 60
  }
}

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

验证回调数据结构，按 ID 去重，更新您自己的任务记录，并快速响应。

callback_url 必须是 HTTPS，并且不得指向私有、回环或链路本地网络范围。

错误

当 API 请求本身失败时，例如参数无效、API 密钥无效、积分不足、速率限制或任务未找到等，POST /v1/videos/generations 和 GET /v1/tasks/:id 将返回此错误结构。某些错误会根据情况包含额外字段，例如 required、available 或 retry_after。

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this task.",
    "required": 60,
    "available": 12
  }
}

代码	HTTP	含义	重试？
`invalid_request`	400	缺少或无效参数。	否，请修正请求。
`invalid_api_key`	401	API 密钥缺失、无效或已撤销。	否，请使用有效密钥。
`insufficient_credits`	402	积分不足。任务未被接受或收费。	充值后重试。
`forbidden`	403	API 密钥缺少所需权限范围。	否。
`not_found`	404	任务不存在或不属于密钥所有者。	否。
`rate_limited`	429	请求速率超出限制。	是，遵循 Retry-After 头部。
`internal_error`	500	服务器错误。	是，稍后重试。

速率限制

速率限制针对每个 API 密钥使用滑动窗口应用。生成默认为每分钟 60 个请求；状态查询更宽松。HTTP 429 响应包含 Retry-After。

生成

60/min

状态查询

更宽松

429 响应头

Retry-After

计费与积分

API 采用提交时预留、成功时扣费、失败时退款的计费方式。仪表板使用情况页面显示 API 积分历史记录、任务日志和基于时间的用量统计信息。

已保留

任务被接受时，积分已检查并保留。

已扣费

已完成的任务会结算现有的预留。

已退款

失败或超时的任务会自动退还保留的积分。

在仪表板中检查用量

查看 API 日志、任务时间线、积分历史记录和基于时间的用量指标。

API 日志