Seedance API

利用 Seedance 2.5 或 Seedance 2.0、异步任务、Webhook 及积分计费系统，将视频生成能力集成到您的产品中。

Base URL

https://api.seevio.ai

本页目录

简介

您可以通过本 API 以编程方式提交 Seedance 2.5 和 Seedance 2.0 视频生成任务。推荐使用 Seedance 2.5 模型，它支持文本生成视频、首帧或首尾帧图片生成视频，以及多模态参考视频生成。视频生成采用异步机制：提交任务后会立即返回任务 ID，随后您可以通过轮询任务接口或接收 Webhook 回调来获取最终生成的视频。

异步任务

轮询非常适合开发调试和简单的系统集成。

支持 Webhook

推荐在生产环境中使用 Webhook，这样可以避免高频轮询，并在任务到达最终状态（成功或失败）时及时通知您的服务。

积分管理

提交任务时会先预留相应的积分。任务生成成功后将正式扣除预留积分；若任务失败或超时，预留积分将自动退回。

身份验证

请在控制台中创建 API 密钥，并在每次发送请求时将其作为 Bearer 令牌置于请求头中。完整的密钥仅在创建时显示一次，请妥善保管。

Authorization: Bearer sk_live_xxxxxxxx

sk_live_

生产环境流量请使用 sk_live_ 前缀的密钥。

sk_test_

沙盒测试请使用 sk_test_ 前缀的密钥，其 API 协议与生产环境完全一致。

401

如果密钥缺失、无效或已被撤销，接口将返回 invalid_api_key 错误及 HTTP 401 状态码。

快速上手

首先提交一个生成任务。任务被系统受理后，您可以选择以下一种方式获取结果：轮询任务状态接口，或者通过 Webhook 接收最终生成的视频。

1. 提交生成任务

创建一个异步视频生成任务，系统会立即返回一个任务 ID。

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

方式一：主动轮询

如果您的系统更适合主动拉取数据，可以定期请求任务状态接口以获取最新进度。

curl https://api.seevio.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 发送请求即可创建视频生成任务。请求体中包含顶层模型参数 model、可选的 callback_url，以及包含提示词和生成配置的 input 对象。

POST

/v1/videos/generations

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

生成模式

参数 generation_type 决定了接口接受哪些媒体输入以及模型如何解析这些输入。

Seedance 2.5 功能特性

seedance-2-5

将 model 设置为 seedance-2-5，即可生成时长 4 至 30 秒、分辨率为 480p 或 720p 的视频。

文本生成视频：支持自适应比例，或指定 16:9、9:16、1:1、4:3、3:4、21:9 等视频比例
图片生成视频：支持单张图片（作为首帧）或两张图片（分别作为首帧和尾帧）；此时视频比例必须设置为 adaptive（自适应）
多模态参考视频生成：支持最多 30 张图片、10 个视频和 10 个音频文件，参考素材总数上限为 50 个
每个参考视频或音频的时长必须在 2 至 30 秒之间；参考视频总时长和参考音频总时长分别不能超过 30 秒
支持仅使用音频作为参考输入，支持 return_last_frame（返回最后一帧图）；不支持 seed（随机种子）

生成模式	必填媒体素材	选填媒体素材	备注
`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 个分别作为首帧和尾帧。视频和音频输入将被忽略。
`reference-to-video`	prompt + 至少一个图片、视频或音频参考	在素材限制范围内的图片、视频和音频	Seedance 2.5 支持仅提供音频参考。对于 Seedance 2.0，在提供音频时必须至少包含一个图片或视频。

text-to-video

当提示词（prompt）是唯一的创意输入时，请使用文本生成视频模式。

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

image-to-video

当 input.image_urls 包含 1 到 2 个图片 URL 时，请使用图片生成视频模式：传入 1 个 URL 代表首帧，传入 2 个 URL 分别代表首帧和尾帧。在此模式下，传入的视频和音频参考将被忽略。

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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

如果您需要通过参考图片、视频或音频来进行更精细的画面引导，请使用参考视频生成模式。Seedance 2.5 支持仅使用音频作为参考；而 Seedance 2.0 在提供音频时，必须同时提供至少一张图片或一个视频。

参考素材数量限制

Seedance 2.5：最多支持 30 张参考图片
Seedance 2.5：最多支持 10 个参考视频，单个时长 2-30 秒，总时长不超过 30 秒
Seedance 2.5：最多支持 10 个参考音频，单个时长 2-30 秒，总时长不超过 30 秒
Seedance 2.5：所有类型的参考素材总数最多不超过 50 个
Seedance 2.0 各版本维持原有限制：最多 9 张图片、3 个视频、3 个音频，且视频/音频组总时长不超过 15 秒

支持的输入组合

文本 + 图片

文本 + 视频

文本 + 音频 (仅限 Seedance 2.5)

文本 + 图片 + 视频

文本 + 图片 + 音频

文本 + 视频 + 音频

文本 + 图片 + 视频 + 音频

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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": "720p"
    }
  }'

请求参数

参数名称、枚举值、接口路径和示例均为 API 协议的组成部分。下表详细说明了每个字段的具体行为和作用。

请求头

请求头	是否必填	说明	示例
`Authorization`	是	用于接口鉴权的 Bearer 格式 API 密钥。	`Bearer sk_live_xxx`
`Content-Type`	是	所有写入类请求均需使用 JSON 格式。	`application/json`

顶层参数

字段名称	类型	是否必填	默认值	范围 / 枚举值	适用模式	示例
`model` 用于生成视频的模型版本。Seedance 2.5 请使用 seedance-2-5，Seedance 2.0 请使用 seedance-2-0，Seedance 2.0 Fast 请使用 seedance-2-0-fast，Seedance 2.0 Mini 请使用 seedance-2-0-mini。	string	是	-	seedance-2-5 \| seedance-2-0 \| seedance-2-0-fast \| seedance-2-0-mini	全部	`seedance-2-5`
`callback_url` HTTPS 回调接口，用于接收任务完成或失败的异步通知。	string	否	-	HTTPS 协议 URL，不支持私有网络/内网地址	全部	`https://your-domain.com/hook`
`input` 生成配置和媒体参考素材。	object	是	-	-	全部	`-`

`input.*` 配置参数

字段名称	类型	是否必填	默认值	范围 / 枚举值	适用模式	示例
`input.prompt` 描述视频画面的文本提示词。	string	是	-	非空文本	全部	`a cat surfing`
`input.generation_type` 生成模式。默认为文本生成视频。	string	否	text-to-video	text-to-video \| image-to-video \| reference-to-video	-	`image-to-video`
`input.image_urls` 可公开访问的图片 URL。对于图片生成视频，传入 1 张作为首帧，或传入 2 张分别作为首帧和尾帧。对于参考生成，Seedance 2.5 支持最多 30 张图片，Seedance 2.0 支持最多 9 张。	string[]	条件性必填	[]	图片生成视频模式：1 或 2 张图片。参考生成模式：Seedance 2.5 最多 30 张；Seedance 2.0 最多 9 张。	图片生成视频 / 参考生成视频	`["https://.../a.jpg"]`
`input.video_urls` 仅适用于参考生成模式，且必须为可公开访问的视频 URL。Seedance 2.5 最多支持 10 个视频，单个时长 2-30 秒且总播放时长 <= 30 秒。Seedance 2.0 最多支持 3 个且总播放时长 <= 15 秒。	string[]	否	[]	Seedance 2.5：最多 10 个视频，单个 2-30 秒，总时长 <= 30 秒。Seedance 2.0：最多 3 个，总时长 <= 15 秒。	参考生成视频	`[]`
`input.audio_urls` 仅适用于参考生成模式，且必须为可公开访问的音频 URL。Seedance 2.5 最多支持 10 个音频，单个时长 2-30 秒且总播放时长 <= 30 秒，并支持仅提供音频参考。Seedance 2.0 最多支持 3 个且总播放时长 <= 15 秒。	string[]	否	[]	Seedance 2.5：最多 10 个音频，单个 2-30 秒，总时长 <= 30 秒。Seedance 2.0：最多 3 个，总时长 <= 15 秒。	参考生成视频	`[]`
`input.duration` 输出视频的时长（秒）。	int	否	5	Seedance 2.5：4-30 秒。Seedance 2.0：4-15 秒。	全部	`5`
`input.aspect_ratio` 输出视频的宽高比。设置为 adaptive 可以让系统自动推断最佳比例。Seedance 2.5 图片生成视频模式下仅支持 adaptive。	string	否	adaptive	16:9 \| 4:3 \| 1:1 \| 3:4 \| 9:16 \| 21:9 \| adaptive	全部	`16:9`
`input.resolution` 输出视频的分辨率档位。	string	否	720p	Seedance 2.5：480p \| 720p。Seedance 2.0：480p \| 720p \| 1080p \| 4k（取决于具体机型版本）。	全部	`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` 适用于 Seedance 2.0 各版本的确定性随机种子。Seedance 2.5 不支持此参数，请勿传值。	int	否	-1	-1 或 0-4294967295	全部	`-1`

生成任务消耗的积分会根据分辨率、视频时长、所选模型以及参考生成中是否包含视频素材而有所不同。创建任务时返回的 response 中 credits 字段的值即为该任务实际预留的积分。

查看积分计费规则

返回响应

这是 POST /v1/videos/generations 接口请求成功的返回示例。这表明任务已成功创建并被系统受理，相应的积分已被预留。您可以记录返回的 taskId，用于轮询 GET /v1/tasks/:id 接口或在接收 Webhook 回调时匹配任务状态。

POST /v1/videos/generations 成功返回示例

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

获取任务状态

通过 GET /v1/tasks/:id 接口可以获取任务的最新状态。建议轮询间隔不要低于 10 秒。在生产环境中，强烈建议使用 Webhook 回调机制。

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

任务生成成功返回示例

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seevio.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-5",
  "billing_status": "refunded",
  "credits": 100,
  "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 字段将变为空。请务必在有效期结束前将视频文件下载并保存到您的存储服务中。

Webhooks

若在提交任务时配置了 callback_url，Seedance 会在任务完成或失败时向您的接口发送 POST 请求，并附带包含最终结果的 JSON 数据。如果您的接收端返回了非 2xx 状态码，或者在 15 秒内未做出响应，系统最多会重试推送 5 次。重试推送会使用相同的 task id，请在您的系统端做好幂等去重。一旦您成功记录了回调数据，请立即返回 HTTP 200 响应。

任务成功 Webhook 回调示例

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

任务失败 Webhook 回调示例

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

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 协议地址，且不得指向私有、环回（loopback）或链路本地（link-local）等内网网段。

错误处理

当 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": 100,
    "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 密钥以滑动窗口形式应用。视频生成接口默认限制为每分钟 100 次请求；状态查询接口的限制相对宽松。当收到 HTTP 429 响应时，返回头中会包含 Retry-After 字段提示重试等待时间。

生成接口

100/分钟

查询接口

更宽松的限频

429 响应头

Retry-After

计费与积分

API 采用“提交时预留积分、成功时扣除积分、失败时退回积分”的计费机制。您可以在控制台的使用记录页面查看 API 积分历史、任务日志以及多维度的用量统计看板。

积分预留

任务被受理时，系统会校验并预留所需的积分。

实际扣除

视频生成成功后，预留的积分将正式扣除。

自动退款

若任务因故生成失败或超时，预留的积分将自动退回。

在控制台中监控用量

直观查看 API 请求日志、任务耗时、算力消费流水以及基于时间维度的统计图表。

查看 API 日志