Seedance API 开发者指南 2026：集成、端点与最佳实践

构建 AI 视频生成应用需要可靠的 API 访问、清晰的文档和可预测的定价。本指南涵盖了开发者将 Seedance 集成到其应用中所需了解的一切——从身份验证和端点到速率限制、错误处理和生产最佳实践。

什么是 Seedance API？

Seedance API 提供对 Seedance AI 视频生成能力的编程访问。开发者可以通过 RESTful API 将 Seedance 集成到 Web 应用、移动应用、后端服务和自动化工作流中，该 API 接受文本或图像输入并返回生成的视频内容。

该 API 支持与 Web 界面相同的核心功能：

• 文本转视频：根据文本提示生成视频
• 图像转视频：将静态图像动画化为视频
• 风格控制：通过提示应用视觉风格参数
• 分辨率选项：720p 和 1080p 输出

入门：身份验证

API 密钥设置

通过您的账户仪表板访问 Seedance API：

1. 登录 seedance.tv
2. 导航至 设置 → API
3. 生成 API 密钥
4. 安全存储密钥——它授予对您账户的完全访问权限

切勿在客户端代码中暴露您的 API 密钥。 始终从后端服务器进行 API 调用。

身份验证标头

所有 API 请求必须在授权标头中包含您的 API 密钥：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

核心端点

文本转视频生成

POST /api/v1/generate/text-to-video

请求体：

{
  "prompt": "Aerial view of a mountain range at golden hour, slow drone shot, cinematic",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "style": "cinematic"
}

响应：

{
  "job_id": "job_abc123",
  "status": "queued",
  "estimated_completion": "2026-04-20T10:00:30Z",
  "credits_used": 10
}

视频生成是异步的。响应包含一个 job_id，用于轮询完成状态。

图像转视频生成

POST /api/v1/generate/image-to-video

请求体：

{
  "image_url": "https://your-storage.com/source-image.jpg",
  "prompt": "Camera slowly pulls back to reveal the full scene",
  "duration": 6,
  "resolution": "1080p",
  "motion_intensity": 0.7
}

或者直接上传图像：

{
  "image_base64": "BASE64_ENCODED_IMAGE_DATA",
  "prompt": "...",
  "duration": 6
}

任务状态检查

GET /api/v1/jobs/{job_id}

响应：

{
  "job_id": "job_abc123",
  "status": "completed",
  "created_at": "2026-04-20T10:00:00Z",
  "completed_at": "2026-04-20T10:00:45Z",
  "output": {
    "video_url": "https://cdn.seedance.tv/output/job_abc123.mp4",
    "thumbnail_url": "https://cdn.seedance.tv/output/job_abc123_thumb.jpg",
    "duration": 8,
    "resolution": "1080p",
    "file_size_mb": 24.5
  }
}

状态值：queued → processing → completed / failed

列出任务

GET /api/v1/jobs?limit=20&offset=0&status=completed

返回您账户的分页生成任务列表。

错误处理

标准错误响应格式

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded. Retry after 60 seconds.",
    "retry_after": 60
  }
}

常见错误码

重试策略

对可重试的错误实现指数退避：

import time
import requests

def generate_with_retry(prompt: str, max_retries: int = 3) -> dict:
    base_delay = 1.0
    for attempt in range(max_retries):
        try:
            response = requests.post(
                'https://api.seedance.tv/v1/generate/text-to-video',
                headers={'Authorization': f'Bearer {API_KEY}'},
                json={'prompt': prompt, 'duration': 8}
            )
            if response.status_code == 429:
                retry_after = response.json().get('error', {}).get('retry_after', 60)
                time.sleep(retry_after)
                continue
            if response.status_code >= 500:
                delay = base_delay * (2 ** attempt)
                time.sleep(delay)
                continue
            response.raise_for_status()
            return response.json()
        except requests.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(base_delay * (2 ** attempt))
    raise Exception("Max retries exceeded")

轮询任务完成

生成通常需要 30-90 秒。实现高效轮询：

import time
import requests

def wait_for_completion(job_id: str, timeout: int = 300) -> dict:
    """Poll job status until complete or timeout."""
    start_time = time.time()
    poll_interval = 5  # Start with 5-second intervals
    
    while time.time() - start_time < timeout:
        response = requests.get(
            f'https://api.seedance.tv/v1/jobs/{job_id}',
            headers={'Authorization': f'Bearer {API_KEY}'}
        )
        job = response.json()
        
        if job['status'] == 'completed':
            return job['output']
        elif job['status'] == 'failed':
            raise Exception(f"Job {job_id} failed")
        
        # Back off polling interval over time
        poll_interval = min(poll_interval * 1.5, 30)
        time.sleep(poll_interval)
    
    raise TimeoutError(f"Job {job_id} timed out after {timeout} seconds")

速率限制

免费层速率限制

生产环境速率限制

生产应用可获得更高的速率限制。联系 Seedance 支持以获取企业级速率限制提升。

速率限制标头

API 响应在标头中包含速率限制信息：

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

完整 Python SDK 示例

import time
import requests
from typing import Optional

class SeedanceClient:
    BASE_URL = "https://api.seedance.tv/v1"
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        })
    
    def generate_text_to_video(
        self,
        prompt: str,
        duration: int = 8,
        resolution: str = "1080p",
        aspect_ratio: str = "16:9"
    ) -> str:
        """Submit a text-to-video generation job. Returns job_id."""
        response = self.session.post(
            f"{self.BASE_URL}/generate/text-to-video",
            json={
                "prompt": prompt,
                "duration": duration,
                "resolution": resolution,
                "aspect_ratio": aspect_ratio
            }
        )
        response.raise_for_status()
        return response.json()['job_id']
    
    def generate_image_to_video(
        self,
        image_url: str,
        prompt: str,
        duration: int = 6,
        motion_intensity: float = 0.5
    ) -> str:
        """Submit an image-to-video generation job. Returns job_id."""
        response = self.session.post(
            f"{self.BASE_URL}/generate/image-to-video",
            json={
                "image_url": image_url,
                "prompt": prompt,
                "duration": duration,
                "motion_intensity": motion_intensity
            }
        )
        response.raise_for_status()
        return response.json()['job_id']
    
    def wait_for_job(self, job_id: str, timeout: int = 300) -> dict:
        """Poll until job completes. Returns output dict."""
        start = time.time()
        interval = 5
        
        while time.time() - start < timeout:
            response = self.session.get(f"{self.BASE_URL}/jobs/{job_id}")
            response.raise_for_status()
            job = response.json()
            
            if job['status'] == 'completed':
                return job['output']
            elif job['status'] == 'failed':
                raise Exception(f"Job failed: {job_id}")
            
            interval = min(interval * 1.2, 20)
            time.sleep(interval)
        
        raise TimeoutError(f"Job timeout: {job_id}")
    
    def create_video(
        self,
        prompt: str,
        duration: int = 8,
        resolution: str = "1080p"
    ) -> dict:
        """End-to-end: submit job, wait for completion, return output."""
        job_id = self.generate_text_to_video(prompt, duration, resolution)
        return self.wait_for_job(job_id)


# Usage example
client = SeedanceClient(api_key="your_api_key_here")

output = client.create_video(
    prompt="Luxury watch on marble surface, dramatic lighting, slow rotation, cinematic",
    duration=8,
    resolution="1080p"
)

print(f"Video URL: {output['video_url']}")
print(f"Duration: {output['duration']}s")
print(f"File size: {output['file_size_mb']}MB")

Node.js / TypeScript 示例

interface GenerateOptions {
  prompt: string;
  duration?: number;
  resolution?: '720p' | '1080p';
  aspectRatio?: '16:9' | '9:16' | '1:1';
}

interface JobOutput {
  videoUrl: string;
  thumbnailUrl: string;
  duration: number;
  fileSizeMb: number;
}

class SeedanceClient {
  private baseUrl = 'https://api.seedance.tv/v1';
  private headers: Record<string, string>;

  constructor(apiKey: string) {
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    };
  }

  async generateVideo(options: GenerateOptions): Promise<string> {
    const response = await fetch(`${this.baseUrl}/generate/text-to-video`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({
        prompt: options.prompt,
        duration: options.duration ?? 8,
        resolution: options.resolution ?? '1080p',
        aspect_ratio: options.aspectRatio ?? '16:9',
      }),
    });
    const data = await response.json();
    return data.job_id;
  }

  async waitForJob(jobId: string, timeoutMs = 300_000): Promise<JobOutput> {
    const start = Date.now();
    let interval = 5000;

    while (Date.now() - start < timeoutMs) {
      const response = await fetch(`${this.baseUrl}/jobs/${jobId}`, {
        headers: this.headers,
      });
      const job = await response.json();

      if (job.status === 'completed') return job.output;
      if (job.status === 'failed') throw new Error(`Job failed: ${jobId}`);

      interval = Math.min(interval * 1.2, 20000);
      await new Promise(r => setTimeout(r, interval));
    }
    throw new Error(`Job timeout: ${jobId}`);
  }

  async createVideo(options: GenerateOptions): Promise<JobOutput> {
    const jobId = await this.generateVideo(options);
    return this.waitForJob(jobId);
  }
}

// Usage
const client = new SeedanceClient(process.env.SEEDANCE_API_KEY!);
const output = await client.createVideo({
  prompt: 'Mountain sunrise, slow aerial drone, cinematic, golden hour',
  duration: 8,
  resolution: '1080p',
});
console.log('Video ready:', output.videoUrl);

Webhook 集成（异步通知）

无需轮询，注册一个 Webhook URL 以接收完成通知：

POST /api/v1/webhooks

{
  "url": "https://your-app.com/webhooks/seedance",
  "events": ["job.completed", "job.failed"],
  "secret": "your_webhook_secret"
}

Webhook 负载（完成时发送到您的端点）：

{
  "event": "job.completed",
  "job_id": "job_abc123",
  "timestamp": "2026-04-20T10:01:15Z",
  "output": {
    "video_url": "https://cdn.seedance.tv/output/job_abc123.mp4",
    "duration": 8,
    "resolution": "1080p"
  }
}

验证 Webhook 签名以防止伪造：

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

生产最佳实践

1. 安全存储 API 密钥

# Use environment variables
import os
api_key = os.environ.get('SEEDANCE_API_KEY')
if not api_key:
    raise ValueError("SEEDANCE_API_KEY environment variable not set")

2. 实现请求队列

对于高容量应用，实现队列以遵守速率限制：

from queue import Queue
import threading

class VideoGenerationQueue:
    def __init__(self, client: SeedanceClient, max_concurrent: int = 2):
        self.client = client
        self.queue = Queue()
        self.semaphore = threading.Semaphore(max_concurrent)
    
    def submit(self, prompt: str) -> str:
        """Add a generation job to the queue. Returns job_id."""
        with self.semaphore:
            job_id = self.client.generate_text_to_video(prompt)
            return job_id

3. 缓存生成的视频

避免重新生成相同内容：

import hashlib
import json
from functools import lru_cache

def get_cache_key(prompt: str, duration: int, resolution: str) -> str:
    params = json.dumps({'prompt': prompt, 'duration': duration, 'resolution': resolution}, sort_keys=True)
    return hashlib.sha256(params.encode()).hexdigest()

# Check cache before generating
cache_key = get_cache_key(prompt, duration, resolution)
if cached_url := video_cache.get(cache_key):
    return cached_url

# Generate and cache
output = client.create_video(prompt=prompt, duration=duration)
video_cache.set(cache_key, output['video_url'], ttl=86400)
return output['video_url']

4. 处理并发用户

对于多个用户同时生成视频的应用：

import asyncio
import aiohttp

async def generate_videos_concurrent(prompts: list[str]) -> list[dict]:
    """Generate multiple videos concurrently with rate limiting."""
    semaphore = asyncio.Semaphore(5)  # Max 5 concurrent jobs
    
    async def generate_one(prompt: str) -> dict:
        async with semaphore:
            # Submit job
            job_id = await submit_job_async(prompt)
            # Wait for completion
            return await wait_for_job_async(job_id)
    
    return await asyncio.gather(*[generate_one(p) for p in prompts])

常见问题

Seedance API 有免费层吗？ 是的。Seedance 在免费层提供 API 访问，但有速率限制。对于需要更高吞吐量的生产应用，请联系 Seedance 了解生产 API 计划。

API 返回什么视频格式？ 默认情况下，API 返回 H.264 编码的 MP4 文件。输出 URL 是一个直接下载链接，有效期为 24 小时。

生成的视频可用多长时间？ 输出视频 URL 可在 24 小时内下载。请将视频下载并存储到您自己的存储中以实现永久访问。

我可以将 API 生成的视频用于商业用途吗？ 是的。Seedance 的免费层包含商业使用权限。通过 API 生成的视频与 Web 生成的内容受相同的商业许可约束。

通过 API 的最大视频时长是多少？ 标准层每次生成为 8 秒。联系 Seedance 以获取延长时长选项。

如何在生产环境中处理错误？ 对 429 和 5xx 错误实现指数退避重试。记录所有失败及其 job_id 以便调试。设置警报以监控错误率升高。

立即在 seedance.tv 开始使用 Seedance 构建 →

高级集成模式

批量视频生成管道

对于需要定期生成大量视频的内容团队，批量管道比单个请求更高效：

import csv
import time
from pathlib import Path
from dataclasses import dataclass

@dataclass
class VideoJob:
    id: str
    prompt: str
    output_filename: str
    status: str = "pending"
    video_url: str = ""

def batch_generate_from_csv(input_csv: str, output_dir: str) -> None:
    """Read prompts from CSV, generate videos, save results."""
    client = SeedanceClient(api_key=os.environ['SEEDANCE_API_KEY'])
    jobs = []
    
    # Read prompts
    with open(input_csv) as f:
        reader = csv.DictReader(f)
        for row in reader:
            jobs.append(VideoJob(
                id=row['id'],
                prompt=row['prompt'],
                output_filename=row.get('filename', f"video_{row['id']}.mp4")
            ))
    
    # Submit all jobs
    pending_jobs = {}
    for job in jobs:
        try:
            job_id = client.generate_text_to_video(job.prompt)
            pending_jobs[job_id] = job
            job.status = "submitted"
            print(f"Submitted: {job.id} → {job_id}")
            time.sleep(0.1)  # Rate limit buffer
        except Exception as e:
            job.status = "submission_failed"
            print(f"Failed to submit {job.id}: {e}")
    
    # Poll all pending jobs
    while pending_jobs:
        completed = []
        for api_job_id, job in pending_jobs.items():
            try:
                output = client.check_job(api_job_id)
                if output['status'] == 'completed':
                    job.video_url = output['output']['video_url']
                    job.status = "completed"
                    completed.append(api_job_id)
                    print(f"Completed: {job.id}")
                elif output['status'] == 'failed':
                    job.status = "failed"
                    completed.append(api_job_id)
            except Exception as e:
                print(f"Error checking {api_job_id}: {e}")
        
        for job_id in completed:
            del pending_jobs[job_id]
        
        if pending_jobs:
            time.sleep(10)
    
    # Save results
    results_file = Path(output_dir) / "results.csv"
    with open(results_file, 'w', newline='') as f:
        writer = csv.DictWriter(f, fieldnames=['id', 'status', 'video_url', 'filename'])
        writer.writeheader()
        for job in jobs:
            writer.writerow({
                'id': job.id,
                'status': job.status,
                'video_url': job.video_url,
                'filename': job.output_filename
            })
    
    print(f"Results saved to {results_file}")
    successful = sum(1 for j in jobs if j.status == 'completed')
    print(f"Completed: {successful}/{len(jobs)}")

与内容管理系统集成

对于使用 CMS 平台的团队，将 Seedance 集成到您的内容管道中：

# Example: WordPress integration via REST API
import requests

def publish_post_with_video(
    wp_url: str,
    wp_credentials: tuple,
    title: str,
    content: str,
    video_prompt: str
) -> dict:
    """Generate a video and publish it alongside a WordPress post."""
    
    # Generate video
    seedance = SeedanceClient(api_key=os.environ['SEEDANCE_API_KEY'])
    output = seedance.create_video(prompt=video_prompt)
    video_url = output['video_url']
    
    # Embed video in post content
    video_embed = f'<video controls src="{video_url}" style="max-width:100%"></video>'
    full_content = f"{video_embed}\n\n{content}"
    
    # Publish to WordPress
    response = requests.post(
        f"{wp_url}/wp-json/wp/v2/posts",
        auth=wp_credentials,
        json={
            "title": title,
            "content": full_content,
            "status": "publish"
        }
    )
    return response.json()

无服务器集成（AWS Lambda / Vercel）

对于无服务器架构，使用异步处理：

# AWS Lambda handler
import json
import boto3

def lambda_handler(event, context):
    """Lambda function triggered by SQS message with video generation request."""
    body = json.loads(event['Records'][0]['body'])
    
    client = SeedanceClient(api_key=os.environ['SEEDANCE_API_KEY'])
    
    try:
        job_id = client.generate_text_to_video(
            prompt=body['prompt'],
            duration=body.get('duration', 8)
        )
        
        # Store job_id for async completion tracking
        dynamodb = boto3.resource('dynamodb')
        table = dynamodb.Table('VideoJobs')
        table.put_item(Item={
            'job_id': job_id,
            'request_id': body['request_id'],
            'status': 'processing',
            'created_at': int(time.time())
        })
        
        return {'statusCode': 200, 'body': json.dumps({'job_id': job_id})}
    
    except Exception as e:
        return {'statusCode': 500, 'body': json.dumps({'error': str(e)})}

监控与可观测性

对于生产应用，实现全面的监控：

import logging
from datetime import datetime

# Configure structured logging
logging.basicConfig(
    format='%(asctime)s %(levelname)s %(name)s %(message)s',
    level=logging.INFO
)
logger = logging.getLogger('seedance.api')

class MonitoredSeedanceClient(SeedanceClient):
    def create_video(self, **kwargs) -> dict:
        start = datetime.now()
        try:
            result = super().create_video(**kwargs)
            duration_ms = (datetime.now() - start).total_seconds() * 1000
            logger.info("video_generated", extra={
                'prompt_length': len(kwargs.get('prompt', '')),
                'duration_ms': duration_ms,
                'resolution': kwargs.get('resolution', '1080p')
            })
            return result
        except Exception as e:
            logger.error("video_generation_failed", extra={
                'error': str(e),
                'prompt': kwargs.get('prompt', '')[:100]
            })
            raise

在生产环境中跟踪以下关键指标：

• 生成延迟：P50、P95、P99 完成时间
• 错误率：按错误代码分类，设置告警阈值
• 积分消耗：每日使用量与预算对比
• 队列深度：任何时刻的待处理任务数
• 成功率：成功完成的任务百分比

Seedance API 专为希望将专业 AI 视频生成集成到其应用中的开发者设计。凭借简单的身份验证、清晰的错误代码和灵活的集成模式，您可以在一个开发冲刺中为任何应用添加 AI 视频生成功能。

立即在 seedance.tv 使用 Seedance 的免费 API 开始构建 →

构建生产级 AI 视频生成应用需要关注与任何 API 集成相同的工程基础：安全的凭据管理、健壮的错误处理、高效的轮询或 Webhook 模式，以及全面的可观测性。Seedance 提供了开发者友好的 API，使这些集成变得简单直接。无论您是在构建内容自动化管道、面向用户的视频创作工具，还是内部生产工作流，本指南中的模式都为可靠、可扩展的 Seedance API 集成提供了基础。

无限制的免费生成、商业许可和简洁的 API 相结合，使 Seedance 在 AI 视频平台中独具优势。您可以在不产生 API 成本的情况下进行原型设计、测试和发布生产应用——与基于使用量的定价模式相比，这是一个显著的优势，因为后者在开发过程中成本难以预测。从免费层开始，构建您的集成，衡量您的使用模式，并自信地扩展，因为平台支持您的增长。

对于评估 AI 视频 API 的团队，决策通常归结为三个因素：质量、成本和开发者体验。Seedance 在这三个方面都表现出色——专业质量的视频输出、无水印且包含商业许可的免费层，以及行为可预测的简洁 RESTful API。本指南中描述的监控和集成模式确保您的 Seedance 集成在应用复杂性和规模增长时保持可维护性和可观测性。 Seedance API 在设计上对开发者友好——清晰的身份验证、可预测的错误代码以及适用于任何技术栈的灵活集成模式。投入一个冲刺即可完成稳固的集成，回报是无限的 AI 视频生成能力直接集成到您的应用或工作流中。 立即在 seedance.tv 使用免费 API 开始构建，亲身体验 AI 视频生成如何改变您的应用或工作流。