SeeDance视频生成API对接实战指南：从申请到异步回调

本文将详细介绍如何对接使用SeeDance视频生成API，通过输入文本提示词或参考图片来动态生成高质量视频。

申请流程

要开始使用API，您需要先获取访问凭证。登录官方API服务平台后，找到SeeDance Videos Generation API对应的页面。进入页面后，点击「Acquire」按钮来申请服务密钥。

如果您尚未登录或注册账号，系统会自动跳转到登录页面引导您完成注册流程。首次申请时，平台通常会提供一定的免费额度，方便开发者进行初步的集成和测试。

基本使用

了解基本的使用方式是第一步。核心操作非常简单：提供一个文本提示词（content.text）、指定内容类型（content.type=text）并选择生成模型（model），即可发起一个视频生成任务。

如上图所示，我们需要配置两部分内容：请求头（Request Headers）和请求体（Request Body）。

请求头（Request Headers）主要包含：

• accept：指定期望接收的响应格式，通常设置为 application/json。
• authorization：调用API必需的密钥，格式为 Bearer {token}，申请后可在下拉框中选择。

请求体（Request Body）的关键参数如下：

• model：指定用于视频生成的模型ID。可选模型包括 doubao-seedance-1-0-pro-250528、doubao-seedance-1-0-pro-fast-251015、doubao-seedance-1-5-pro-251215、doubao-seedance-1-0-lite-t2v-250428、doubao-seedance-1-0-lite-i2v-250428 等。
• content：输入内容数组，其中每一项必须包含 text 或 image_url，两者互斥。type 字段决定了其他字段的存在和意义。
• service_tier：服务等级，可选 default 或 flex。
• return_last_frame：布尔值，指定是否返回生成视频的最后一帧图像。
• execution_expires_after：任务执行的超时时间（秒）。
• callback_url：用于接收任务完成回调通知的URL（用于异步模式）。

填写好参数后，页面右侧会自动生成可供测试的代码片段。

点击「Try」按钮进行测试，你将收到类似以下的响应：

{
  "success": true,
  "task_id": "ec22ae22-0140-4033-8c86-a48b536da595",
  "trace_id": "1cc87db0-8ee5-4436-969b-35cc571a9fd5",
  "data": {
    "task_id": "cgt-20251222005129-62fhb",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/f592800a-b87c-4705-8796-cbb8018cae35.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}

响应结果解析：

• success: 表示API调用是否成功。
• task_id: 当前视频生成任务的客户端ID。
• trace_id: 用于追踪请求的ID。
• data: 任务的具体结果数据。
  • task_id: 服务器端的任务ID。
  • status: 任务状态（如 succeeded）。
  • video_url: 生成的视频文件访问链接。
  • model: 实际使用的模型。

获取到结果后，直接访问 data.video_url 即可下载生成的视频。为了方便集成，你可以直接复制生成的代码，例如下面这条cURL命令：

curl -X POST 'https://api.acedata.cloud/seedance/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "content": [{"text":"A kitten yawning at the camera. --rs 720p --rt 16:9 --dur 5 --fps 24 --wm true --seed 11 --cf false","type":"text"}],
  "model": "doubao-seedance-1-0-pro-250528"
}'

图生视频（指定首帧）

如果你想让生成的视频以一张特定图片作为开头，需要使用图生视频功能。此时，content 参数中需要包含一个类型为 image_url 的项，并在其 url 字段传入参考图片的链接或Base64编码。

Base64编码格式必须严格遵守：data:image/<图片格式>;base64,<Base64编码>。注意 <图片格式> 需为小写，例如 data:image/png;base64,{base64_image}。

以下是一个使用Python requests 库进行图生视频（首帧）请求的示例代码：

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "content": [
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
            }
        },
        {
            "type": "text",
            "text": "A girl holds a fox in her arms. She opens her eyes and gazes tenderly at the camera, while the fox affectionately holds her back. As the camera slowly pulls away, her hair is gently blown by the wind. --ratio adaptive  --dur 5"
        }
    ],
    "model": "doubao-seedance-1-0-pro-250528"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

运行后，你会得到与文本生成视频类似结构的响应，其中包含了基于参考图生成的视频链接。

图生视频（指定首尾帧）

更进一步，你还可以同时指定视频的首帧和尾帧图像，让AI生成中间连贯的动画。这时，需要在 content 数组中传入两个类型为 image_url 的对象，并分别设置其 role 字段为 first_frame 和 last_frame。

• role: 用于指定图片角色，first_frame 代表首帧，last_frame 代表尾帧。
• image_url.url: 图片链接。同时，content 中仍需包含一个 type 为 text 的项作为描述视频内容的提示词。

参考代码示例：

import requests

url = "https://api.acedata.cloud/sora/videos"  # 注意：原文此处为`sora`，实际应为`seedance`，保留原文错误供参考

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
        {
            "type": "text",
            "text": "360-degree shot"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
            },
            "role": "first_frame"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
            },
            "role": "last_frame"
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

异步回调

视频生成通常耗时较长（约1-2分钟）。如果采用同步请求，HTTP连接会长时间保持，消耗不必要的系统资源。因此，API提供了异步回调的支持。

其工作流程如下：

1. 客户端发起请求时，在请求体中额外指定 callback_url 字段。
2. API立即返回一个仅包含 task_id 的响应，表明任务已接收。
3. 当视频生成任务在服务器端完成后，系统会向您提供的 callback_url 发起一个POST请求，请求体为完整的任务结果JSON（包含相同的 task_id 用于关联）。

发起异步请求后，会立即收到如下响应：

{
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}

任务完成后，您的 callback_url 将接收到推送的结果，格式与同步请求成功时的一致：

{
  "success": true,
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
  "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
  "data": {
    "task_id": "cgt-20251222073134-54qcw",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}

错误处理

在调用API过程中，如果遇到问题，API会返回对应的错误码和信息。了解这些常见的错误类型有助于快速定位和解决问题。

• 400 token_mismatched：请求参数缺失或无效。
• 400 api_not_implemented：请求参数缺失或无效。
• 401 invalid_token：授权token无效或缺失。
• 429 too_many_requests：请求频率超限。
• 500 api_error：服务器内部错误。

错误响应示例：

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

通过以上步骤，你应该已经掌握了如何使用SeeDance视频生成API进行文本生视频、图生视频以及如何处理异步任务。在对接过程中，仔细查阅官方技术文档并妥善处理各种可能的错误响应，是确保集成顺利的关键。如果在开发中遇到更复杂的技术问题，也可以在 云栈社区 的对应板块与其他开发者交流探讨。