API 文档

使用 Seevio API 进行开发

将视频生成功能无缝接入您的产品。只需选择模型、提交请求，即可通过轮询或 Webhook 获取生成结果。

创建 API 密钥 API 控制台

选择模型

每个模型的参考文档中均包含完整的参数说明、计费细则和代码示例。您可以在单个模型页面中完成所有集成工作。

Seedance 2.5

480p · 720p · 1080p

4–30 秒

阅读模型文档

Seedance 2.0

480p · 720p · 1080p · 4k

4–15 秒

阅读模型文档

Seedance 2.0 Fast

480p · 720p

4–15 秒

阅读模型文档

Seedance 2.0 Mini

480p · 720p

4–15 秒

阅读模型文档

身份验证

请在控制台中创建 API 密钥。完整的密钥仅会显示一次，请妥善保存在您的服务器上，并在每次发起 API 请求时将其作为 Bearer 令牌携带于请求头中。

创建 API 密钥 API 控制台

基础 URL

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

在运行示例代码前，请先设置 SEEVIO_API_KEY 环境变量。JavaScript 示例适用于 Node.js 服务端环境；Python 示例需使用 requests 库。

快速开始

本示例展示了如何使用 Seedance 2.5 生成一个 5 秒、720p 的视频。如需了解完整的生成模式和参数限制，请参阅具体模型的参考文档。

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

创建任务的响应示例

上方请求被成功接收后，接口会返回以下 JSON。taskId 是任务标识，用于后续查询任务状态；credits 是本次任务预扣的积分数量。此响应仅表示任务已创建，不代表视频已生成完成。你需要使用轮询查询任务状态，或通过 Webhook 来接收视频结果。

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 100
}

查询任务状态

GET https://api.seevio.ai/v1/tasks/{taskId}

请将示例中的 ID 替换为创建任务时返回的 taskId。查询接口仅支持查询当前 API 密钥所属用户的任务；若 ID 无权访问或不存在，将返回 HTTP 404 错误。

建议每 10–20 秒轮询一次，遇到 HTTP 429 时请增加重试间隔（退避），并在状态为 completed 或 failed 时停止轮询。生产环境中推荐使用 Webhook。下方的代码示例均只执行单次查询。

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

状态	说明及约束
`queued`	任务已接收，正在排队等待调度。
`generating`	视频正在生成中。
`completed`	生成成功。请在视频链接过期前下载 data.results 中的文件。
`failed`	生成失败。可以通过 failed_reason 和 billing_status 排查原因。

字段	类型	说明及约束
`id`	string	任务唯一标识。即创建任务响应中返回的 taskId。
`created_at`	number	任务创建的 Unix 时间戳（秒）。
`model`	string	执行该任务所调用的公共模型 ID。
`billing_status`	string	计费状态：reserved（已预扣）、charged（已扣除）、refunded（已退款）或 refund_failed（退款失败）。
`credits`	number	该任务预扣的积分。发生退款后，此数值仍会保留；请通过 billing_status 判断最终的实际扣费结果。
`failed_reason`	string \| null	任务失败时的具体原因；任务未失败时为 null。失败任务的查询响应中会省略 data 字段。
`data`	object	任务成功生成或处于处理中时存在。包含输出内容和处理详情。
`data.results`	string[]	生成的视频 URL 数组。在任务完成前或视频过期后，该数组为空。
`data.video_expires_at`	string \| null	视频过期时间，格式为 ISO 8601 时间戳；暂不可用时为 null。请在此时间前下载并保存结果。
`data.last_frame_url`	string \| null	请求了最后一帧且成功获取时返回其 URL，否则为 null。
`data.processing_time`	number \| null	服务商的处理耗时（秒）；暂不可用时为 null。

任务已完成：查询响应与视频结果

查询返回 status 为 completed 时，表示视频已生成完成。你可以从 data.results 获取视频地址，并在 data.video_expires_at 指定的过期时间前下载保存。billing_status 为 charged 表示本次任务已按预扣积分完成扣费。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

任务已失败：查询响应与退款状态

查询返回 status 为 failed 时，表示视频生成未成功。请通过 failed_reason 查看失败原因，通过 billing_status 确认退款结果。以下示例中的 refunded 表示积分已退还；credits 仍保留原预扣积分数量，失败响应不包含 data 字段。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "failed",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

Webhook

在生产环境中，建议您在创建任务时提供 callback_url。每个模型的参考文档中都附带了回调数据格式和接收端服务代码示例。

在创建任务的请求中设置 callback_url，当任务完成或失败时，系统将向该地址发送 JSON POST 请求。接收端需在 15 秒内返回 2xx 响应。若推送失败系统会重试，请根据任务 ID（id）在您的接收端做好幂等处理。

你的回调接口需支持接收 POST 请求及 JSON 格式的请求体（Content-Type: application/json）。

创建带有 Webhook 回调的任务

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Webhook 接收的数据格式与主动查询接口略有不同：Webhook 中没有 billing_status 和 credits 字段；失败的详细原因和退款积分会被放在 data.failed_reason 和 data.credits_refunded 中。Webhook 中的 created_at 为该回调事件触发时的 Unix 时间戳（秒）。

任务完成回调：返回生成的视频结果

视频生成成功后，系统会发送 status 为 completed 的回调。你可以通过 id 关联对应任务，从 data.results 获取视频地址，并在 data.video_expires_at 指定的过期时间前下载并保存视频。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

任务失败回调：返回失败原因和退款信息

视频生成失败后，系统会发送 status 为 failed 的回调。你可以通过 id 关联对应任务，从 data.failed_reason 查看失败原因，从 data.credits_refunded 查看已退还的积分数量。

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

接收端代码示例

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

  if (callbackData.status === "completed") {
    const videoUrls = callbackData.data.results;
    // Save the video URLs and mark this task as completed in your application.
    console.log(callbackData.id, videoUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData.data;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

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

此 Next.js 示例直接读取回调的 JSON 请求体，分别处理任务完成和失败两种状态。实际接入时，请补充数据存储及按任务 ID 去重的逻辑；耗时操作建议先放入队列，再及时返回响应。

错误处理

发生 HTTP 错误时将返回一个包含 code 和 message 的 error 对象。成功创建的任务仍有可能在后续处理中失败，请及时查询任务状态或处理失败回调。

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

HTTP	字段	解决方法
400	`invalid_request`	请求参数有误，请在重试前修正 JSON 格式、缺失的提示词、参数取值范围或媒体文件 URL。
401	`invalid_api_key`	身份验证失败，请检查您的 Bearer 令牌及 API 密钥是否处于启用状态。
402	`insufficient_credits`	账户余额不足。请充值或降低本次任务的生成配置。响应中可能会返回当前任务所需积分及您的可用积分。
403	`forbidden`	请检查错误信息中提示的账户限制。
404	`not_found`	未找到相关资源。请检查任务 ID 是否正确，以及该密钥是否属于发起该任务的用户。
429	`rate_limited`	请求过于频繁，请在 Retry-After 指定的时间间隔后再进行重试。
500	`internal_error`	服务器内部错误。请查看错误消息和 API 日志。重试时请保持谨慎；重新发送创建请求可能会创建新的计费任务。