AIVidPipeline

Seedance 2.0 API：完整集成指南（2026）

2026/02/11

Seedance 2.0 API 提供了对字节跳动 AI 视频生成模型的编程访问接口。本指南涵盖开发者将 Seedance 集成到应用和生产工作流中所需的一切内容，从身份验证到异步轮询再到基于 Webhook 的架构。

API 概览

Seedance 2.0 REST API 提供了文生视频、图生视频、状态轮询和结果获取等端点。所有生成过程都是异步的：你提交一个请求，获得一个任务 ID，然后通过轮询或等待 Webhook 来获取结果。

功能端点方法
文生视频/v2/generate/textPOST
图生视频/v2/generate/imagePOST
状态查询/v2/tasks/{task_id}GET
结果下载/v2/tasks/{task_id}/resultGET
Webhook 配置/v2/webhooksPOST
账户信息/v2/accountGET

基础 URL： https://api.seedance.ai

响应格式： 所有端点返回 JSON 格式，包含统一的 status、data 和 error 字段结构。

快速上手（5 分钟）

只需三个步骤，即可从零开始生成你的第一个视频。

第一步：获取 API 密钥。 在 Dreamina 开发者门户 注册账号，进入设置 > API 密钥页面生成密钥。

第二步：提交生成请求。

curl -X POST https://api.seedance.ai/v2/generate/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "A golden retriever running through a field of sunflowers at sunset, slow motion, cinematic lighting",
    "aspect_ratio": "16:9",
    "duration": 4
  }'

第三步：轮询获取结果。

curl https://api.seedance.ai/v2/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

当 status 返回 "completed" 时，响应中会包含一个 video_url 字段，提供一个有效期为 24 小时的签名下载链接。

身份验证

所有 API 请求都需要在 Authorization 头中携带 Bearer 令牌。你的 API 密钥与账户和计费方案绑定。

JavaScript

const SEEDANCE_API_KEY = process.env.SEEDANCE_API_KEY

const headers = {
  'Authorization': `Bearer ${SEEDANCE_API_KEY}`,
  'Content-Type': 'application/json',
}

Python

import os
import requests

SEEDANCE_API_KEY = os.environ["SEEDANCE_API_KEY"]

headers = {
    "Authorization": f"Bearer {SEEDANCE_API_KEY}",
    "Content-Type": "application/json",
}

cURL

curl -H "Authorization: Bearer $SEEDANCE_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.seedance.ai/v2/account

安全最佳实践：

  • 将 API 密钥存储在环境变量中，绝不要写入源代码
  • 通过开发者控制台定期轮换密钥
  • 为开发环境和生产环境使用不同的密钥
  • 通过账户面板监控用量，及时发现未授权使用

文生视频端点

根据文本描述生成视频。这是大多数使用场景的主要端点。

请求参数：

参数类型必填默认值说明
modelstring是—模型版本（seedance-2.0）
promptstring是—视频描述（30-500 字符）
negative_promptstring否—需要排除的元素
aspect_ratiostring否16:916:9、9:16 或 1:1
durationinteger否44 或 8 秒
seedinteger否随机可复现性种子值
webhook_urlstring否—完成通知的回调 URL

JavaScript 示例

async function generateTextToVideo(prompt) {
  const response = await fetch('https://api.seedance.ai/v2/generate/text', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      model: 'seedance-2.0',
      prompt,
      aspect_ratio: '16:9',
      duration: 4,
    }),
  })

  const data = await response.json()

  if (!data.data?.task_id) {
    throw new Error(`Generation failed: ${data.error?.message ?? 'Unknown error'}`)
  }

  return data.data.task_id
}

Python 示例

def generate_text_to_video(prompt: str) -> str:
    response = requests.post(
        "https://api.seedance.ai/v2/generate/text",
        headers=headers,
        json={
            "model": "seedance-2.0",
            "prompt": prompt,
            "aspect_ratio": "16:9",
            "duration": 4,
        },
    )
    response.raise_for_status()
    data = response.json()

    task_id = data.get("data", {}).get("task_id")
    if not task_id:
        raise ValueError(f"Generation failed: {data.get('error', {}).get('message', 'Unknown')}")

    return task_id

关于如何编写高效的提示词，请参阅我们的 Seedance 提示词指南，内含 50 多个可直接使用的模板。

图生视频端点

通过运动提示词将静态图片转化为动态视频。图片提供视觉起点，运动提示词描述场景的运动方式。

请求参数：

参数类型必填说明
modelstring是seedance-2.0
imagefile/URL是源图片（JPEG/PNG，最大 10MB）
motion_promptstring是期望的运动效果描述
durationinteger否4 或 8 秒
seedinteger否可复现性种子值
webhook_urlstring否完成通知的回调 URL

JavaScript 示例（文件上传）

async function generateImageToVideo(imagePath, motionPrompt) {
  const imageBuffer = await fs.promises.readFile(imagePath)
  const blob = new Blob([imageBuffer], { type: 'image/png' })

  const formData = new FormData()
  formData.append('model', 'seedance-2.0')
  formData.append('image', blob, 'input.png')
  formData.append('motion_prompt', motionPrompt)
  formData.append('duration', '4')

  const response = await fetch('https://api.seedance.ai/v2/generate/image', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${SEEDANCE_API_KEY}` },
    body: formData,
  })

  const data = await response.json()
  return data.data.task_id
}

JavaScript 示例（URL 引用）

async function generateImageToVideoFromUrl(imageUrl, motionPrompt) {
  const response = await fetch('https://api.seedance.ai/v2/generate/image', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      model: 'seedance-2.0',
      image_url: imageUrl,
      motion_prompt: motionPrompt,
      duration: 4,
    }),
  })

  const data = await response.json()
  return data.data.task_id
}

Python 示例

def generate_image_to_video(image_path: str, motion_prompt: str) -> str:
    with open(image_path, "rb") as f:
        files = {"image": ("input.png", f, "image/png")}
        data = {
            "model": "seedance-2.0",
            "motion_prompt": motion_prompt,
            "duration": "4",
        }

        response = requests.post(
            "https://api.seedance.ai/v2/generate/image",
            headers={"Authorization": f"Bearer {SEEDANCE_API_KEY}"},
            files=files,
            data=data,
        )

    response.raise_for_status()
    return response.json()["data"]["task_id"]

异步生成与状态轮询

Seedance API 的所有生成操作都是异步的。提交请求后，你会收到一个 task_id，需要通过轮询来等待完成。根据视频时长和服务器负载，生成通常需要 30-120 秒。

任务状态值：

状态说明
pending请求已接收，排队等待处理
processing正在生成中
completed视频已就绪，可供下载
failed生成失败（详见 error 字段）

JavaScript 轮询实现

async function pollForResult(taskId, maxAttempts = 60, intervalMs = 3000) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://api.seedance.ai/v2/tasks/${taskId}`,
      { headers }
    )
    const data = await response.json()
    const status = data.data?.status

    if (status === 'completed') {
      return data.data.video_url
    }

    if (status === 'failed') {
      throw new Error(`Generation failed: ${data.data?.error ?? 'Unknown error'}`)
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs))
  }

  throw new Error('Generation timed out after maximum polling attempts')
}

Python 轮询实现

import time

def poll_for_result(task_id: str, max_attempts: int = 60, interval: float = 3.0) -> str:
    for _ in range(max_attempts):
        response = requests.get(
            f"https://api.seedance.ai/v2/tasks/{task_id}",
            headers=headers,
        )
        response.raise_for_status()
        data = response.json()["data"]

        if data["status"] == "completed":
            return data["video_url"]

        if data["status"] == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error', 'Unknown')}")

        time.sleep(interval)

    raise TimeoutError("Generation timed out")

轮询最佳实践：

  • 前 30 秒使用 3 秒间隔
  • 超过 30 秒后增加到 5 秒间隔
  • 设置 3-5 分钟的最大超时时间
  • 对被限流的响应实施指数退避策略

Webhook 集成

Webhook 通过在生成完成时向你的服务器推送通知，消除了轮询的需要。这是生产系统的推荐方案。

Webhook 配置

// Register a webhook endpoint
async function registerWebhook(url) {
  const response = await fetch('https://api.seedance.ai/v2/webhooks', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      url,
      events: ['generation.completed', 'generation.failed'],
    }),
  })

  return response.json()
}

Webhook 载荷

当生成完成时，Seedance 会向你的 Webhook URL 发送一个 POST 请求：

{
  "event": "generation.completed",
  "task_id": "task_abc123",
  "status": "completed",
  "video_url": "https://cdn.seedance.ai/results/...",
  "duration": 4,
  "created_at": "2026-02-11T10:30:00Z",
  "completed_at": "2026-02-11T10:31:15Z"
}

Express.js Webhook 处理器

app.post('/webhooks/seedance', express.json(), (req, res) => {
  const { event, task_id, video_url, status } = req.body

  if (event === 'generation.completed') {
    // Process the completed video
    processCompletedVideo(task_id, video_url)
  }

  if (event === 'generation.failed') {
    // Handle failure
    handleGenerationFailure(task_id)
  }

  res.status(200).json({ received: true })
})

Webhook 安全须知：

  • 验证 Webhook 签名头以确认请求来自 Seedance
  • 仅使用 HTTPS 端点
  • 在 5 秒内返回 200 状态码以避免重试
  • 实现幂等处理以应对重复投递

错误处理

Seedance API 使用标准 HTTP 状态码和结构化的错误响应。正确的错误处理对于生产环境的可靠性至关重要。

错误响应格式：

{
  "status": "error",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "retry_after": 30
  }
}

常见错误码：

HTTP 状态码错误码说明处理方式
400INVALID_PARAMS请求参数有误修正请求体
401UNAUTHORIZEDAPI 密钥无效或已过期检查或轮换密钥
403FORBIDDEN当前方案不支持此操作升级方案
429RATE_LIMITED并发请求过多等待后重试
500INTERNAL_ERROR服务端故障退避重试
503SERVICE_UNAVAILABLE临时维护中延迟后重试

JavaScript 带重试的错误处理

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options)

    if (response.ok) {
      return response.json()
    }

    if (response.status === 429) {
      const data = await response.json()
      const retryAfter = data.error?.retry_after ?? 30
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000))
      continue
    }

    if (response.status >= 500) {
      const backoffMs = Math.pow(2, attempt) * 1000
      await new Promise((resolve) => setTimeout(resolve, backoffMs))
      continue
    }

    const errorData = await response.json()
    throw new Error(`API error ${response.status}: ${errorData.error?.message ?? 'Unknown'}`)
  }

  throw new Error('Maximum retries exceeded')
}

Python 带重试的错误处理

def api_request_with_retry(method: str, url: str, max_retries: int = 3, **kwargs) -> dict:
    for attempt in range(max_retries):
        response = requests.request(method, url, headers=headers, **kwargs)

        if response.ok:
            return response.json()

        if response.status_code == 429:
            retry_after = response.json().get("error", {}).get("retry_after", 30)
            time.sleep(retry_after)
            continue

        if response.status_code >= 500:
            time.sleep(2 ** attempt)
            continue

        response.raise_for_status()

    raise RuntimeError("Maximum retries exceeded")

速率限制与配额

速率限制因方案不同而异，适用于并发请求数而非每日总量。

方案并发请求数每分钟请求数每日限制
免费版2105 次生成
专业版1060100 次生成
企业版50+自定义无限制

速率限制头： 每个 API 响应都包含速率限制信息：

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1707654321

监控这些响应头可以主动管理请求频率，避免在高峰时段触及限制。

构建生产工作流

对于大规模生成视频的生产系统，应实现基于队列的处理方式，以管理并发、优雅处理失败并优化吞吐量。

批处理模式

async function processBatch(prompts) {
  const concurrencyLimit = 5
  const results = []

  for (let i = 0; i < prompts.length; i += concurrencyLimit) {
    const batch = prompts.slice(i, i + concurrencyLimit)

    const batchResults = await Promise.allSettled(
      batch.map(async (prompt) => {
        const taskId = await generateTextToVideo(prompt)
        const videoUrl = await pollForResult(taskId)
        return { prompt, videoUrl }
      })
    )

    const settled = batchResults.map((result) =>
      result.status === 'fulfilled'
        ? result.value
        : { error: result.reason.message }
    )

    results.push(...settled)
  }

  return results
}

基于队列的架构

对于高流量应用，使用消息队列将提交与处理解耦：

Client → API Gateway → Message Queue → Worker Pool → Seedance API
                                            ↓
                                       Status Store → Webhook / Polling

推荐的队列服务： Bull (Redis)、AWS SQS、Google Cloud Tasks 或 RabbitMQ。

费用监控

通过账户端点以编程方式追踪 API 开支：

async function checkUsage() {
  const response = await fetch('https://api.seedance.ai/v2/account', {
    headers,
  })
  const data = await response.json()

  return {
    plan: data.data.plan,
    usedToday: data.data.generations_today,
    limitToday: data.data.generations_limit,
    billingCycleSpend: data.data.current_spend,
  }
}

关于详细定价信息（包括批量折扣），请参阅我们的 Seedance 定价指南。

常见问题

如何获取 Seedance API 密钥？

在 Seedance 开发者门户（Dreamina 平台）创建账号，进入控制台，生成 API 密钥即可。免费版也支持 API 访问。

Seedance API 支持哪些编程语言？

Seedance API 是一个 REST API，任何能发送 HTTP 请求的编程语言都可以使用。官方提供了 JavaScript、Python 和 cURL 的示例代码。

Seedance API 生成视频需要多长时间？

根据分辨率和时长设置，生成通常需要 30-120 秒。API 采用异步轮询机制来检查生成状态。

Seedance API 的速率限制是多少？

速率限制取决于你的方案。免费版允许约 2 个并发请求，专业版最多 10 个，企业版可自定义限制。

Seedance API 支持 Webhook 吗？

支持。你可以配置一个 Webhook URL，在视频生成完成时接收通知，无需进行状态轮询。

Seedance API 可以用于商业项目吗？

可以。专业版和企业版的 API 使用包含商业许可。具体使用权限请查阅服务条款。

相关文章

AIVidPipeline

AIVidPipeline

Seedance 2.0 API：完整集成指南（2026） | AI 视频制作博客 — 教程与工具 | AIVidPipeline