┌─────────────────┐             ┌─────────────────────┐             ┌─────────────────────────┐
│ 客户端服务      │             │ ToAPIs 统一聚合网关 │             │ 字节跳动底层 GPU 集群   │
│ (业务后端 / APP) │             │ (api.toapis.com)    │             │ (Seedance 2.0 渲染引擎) │
└────────┬────────┘             └──────────┬──────────┘             └────────────┬────────────┘
         │                                 │                                     │
         │ 1. POST /v1/videos/generations  │                                     │
         │────────────────────────────────>│ 2. 鉴权校验 & 派发排队任务          │
         │                                 │────────────────────────────────────>│
         │ 3. HTTP 202: 返回 task_id       │                                     │
         │<────────────────────────────────│                                     │
         │                                 │                                     │
         │ 4. GET /v1/tasks/video-status   │                                     │
         │    (间隔 3s 发起轮询)           │                                     │
         │────────────────────────────────>│ 5. 查询任务队列与渲染进度           │
         │                                 │────────────────────────────────────>│
         │ 6. 返回进度: "PROCESSING" (35%) │<────────────────────────────────────│
         │<────────────────────────────────│                                     │
         │                                 │                                     │
         │ 7. GET /v1/tasks/video-status   │                                     │
         │    (间隔 3s 发起轮询)           │                                     │
         │────────────────────────────────>│ 8. 视频渲染完毕，CDN 缓存就绪       │
         │                                 │────────────────────────────────────>│
         │ 9. 返回成功: "SUCCESS" + MP4 URL│<────────────────────────────────────│
         │<────────────────────────────────│                                     │
         │                                 │                                     │
         │ 10. 转存 MP4 至私有云存储(S3)   │                                     │
         │─────────────────────────────────┴─────────────────────────────────────┘

export TOAPIS_API_KEY="sk-toapis-your-active-api-key"

# 步骤 1: 提交视频生成任务
curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "电影级航拍镜头，晨曦雾气中的苏格兰古堡，金色丁达尔光线穿透薄雾，8k超清分辨率 24fps",
    "aspect_ratio": "16:9",
    "duration": 5,
    "quality": "standard"
  }'

{
  "code": 0,
  "message": "Task submitted successfully",
  "data": {
    "task_id": "task_seedance_9f81a7b03c4e4d8a",
    "status": "QUEUED",
    "created_at": 1761037200,
    "model": "doubao-seedance-2-0",
    "estimated_seconds": 32
  }
}

# 步骤 2: 携带返回的 task_id 查询渲染状态
curl -X GET "https://api.toapis.com/v1/tasks/video-status?task_id=task_seedance_9f81a7b03c4e4d8a" \
  -H "Authorization: Bearer $TOAPIS_API_KEY"

"""
Seedance 2.0 视频生成 API 生产级客户端 (通过 ToAPIs 网关)
核心特性:
- 强类型参数构造与数据校验
- 带超时安全保护的智能状态轮询
- 针对 HTTP 429 并发限流的指数抖动退避
- 自动将生成的 MP4 文件流下载至本地磁盘
"""

import os
import time
import random
import logging
from typing import Optional, Dict, Any
import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
logger = logging.getLogger("Seedance2Client")

class SeedanceAPIError(Exception):
    """Seedance API 业务操作异常基类"""
    pass

class SeedanceClient:
    def __init__(self, api_key: Optional[str] = None, base_url: str = "https://api.toapis.com/v1"):
        self.api_key = api_key or os.getenv("TOAPIS_API_KEY")
        if not self.api_key:
            raise ValueError("未找到 API Key。请设置 TOAPIS_API_KEY 环境变量或显式传入。")
        self.base_url = base_url.rstrip("/")
        self.headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
            "User-Agent": "ToAPIs-Seedance-SDK/2.0"
        }

    def submit_video_task(
        self,
        prompt: str,
        aspect_ratio: str = "16:9",
        duration: int = 5,
        quality: str = "standard",
        seed: Optional[int] = None,
        image_url: Optional[str] = None
    ) -> str:
        """
        向 Seedance 2.0 提交视频生成任务，成功后返回 task_id
        """
        url = f"{self.base_url}/videos/generations"
        payload: Dict[str, Any] = {
            "model": "doubao-seedance-2-0",
            "prompt": prompt,
            "aspect_ratio": aspect_ratio,
            "duration": duration,
            "quality": quality
        }
        if seed is not None:
            payload["seed"] = seed
        if image_url:
            payload["image_url"] = image_url

        logger.info(f"正在提交 Seedance 2.0 视频任务: 画幅={aspect_ratio}, 时长={duration}s...")
        response = requests.post(url, json=payload, headers=self.headers, timeout=30)
        
        if response.status_code == 429:
            raise SeedanceAPIError("任务提交触发并发限制 (429)，请在调用层启用排队退避。")
        response.raise_for_status()
        
        data = response.json()
        task_id = data.get("data", {}).get("task_id")
        if not task_id:
            raise SeedanceAPIError(f"网关响应格式不符合预期: {data}")
            
        logger.info(f"任务已进入生成队列，Task ID: {task_id}")
        return task_id

    def poll_until_complete(
        self,
        task_id: str,
        initial_interval: float = 3.0,
        max_timeout: float = 180.0
    ) -> str:
        """
        轮询任务状态直至 SUCCESS 或 FAILED，返回最终的 CDN 视频下载地址
        """
        url = f"{self.base_url}/tasks/video-status"
        params = {"task_id": task_id}
        start_time = time.time()
        current_interval = initial_interval

        while time.time() - start_time < max_timeout:
            time.sleep(current_interval)
            elapsed = int(time.time() - start_time)

            try:
                res = requests.get(url, params=params, headers=self.headers, timeout=15)
            except requests.RequestException as req_err:
                logger.warning(f"网络临时抖动，查询任务 {task_id} 异常: {req_err}，正在重试...")
                continue

            if res.status_code == 429:
                backoff = current_interval * 1.5 + random.uniform(0.5, 1.5)
                logger.warning(f"收到 HTTP 429 限流通知，休眠退避 {backoff:.1f} 秒...")
                time.sleep(backoff)
                continue

            if res.status_code != 200:
                logger.warning(f"状态接口返回 HTTP {res.status_code}: {res.text}")
                continue

            body = res.json().get("data", {})
            status = body.get("status")
            progress = body.get("progress", 0)
            logger.info(f"[已耗时 {elapsed}s] 当前状态: {status} ({progress}%)")

            if status == "SUCCESS":
                video_url = body.get("video_url")
                if not video_url:
                    raise SeedanceAPIError("任务已标记 SUCCESS 但缺失 video_url 字段。")
                logger.info(f"视频渲染成功! 总耗时: {elapsed}s，下载链接: {video_url}")
                return video_url
            elif status in ("FAILED", "CANCELED"):
                error_msg = body.get("error_message", "上游 GPU 集群未知渲染故障。")
                raise SeedanceAPIError(f"Seedance 任务 {task_id} 终止失败: {error_msg}")

        raise TimeoutError(f"任务 {task_id} 超过设定的最大超时阈值 ({max_timeout}s)。")

    def download_video(self, video_url: str, output_path: str) -> None:
        """流式下载视频文件并持久化存储至本地"""
        logger.info(f"开始从 CDN 下载视频流并保存至 {output_path}...")
        with requests.get(video_url, stream=True, timeout=60) as r:
            r.raise_for_status()
            with open(output_path, "wb") as f:
                for chunk in r.iter_content(chunk_size=8192):
                    f.write(chunk)
        logger.info(f"视频落盘完毕: {output_path} (文件大小: {os.path.getsize(output_path)} 字节)")

if __name__ == "__main__":
    client = SeedanceClient()
    prompt_text = "特写微距镜头：液态红铜缓缓注入精密齿轮模具中，火花飞溅，暗色机械车间氛围，光影追踪质感，1080p 30fps"
    
    try:
        t_id = client.submit_video_task(prompt=prompt_text, aspect_ratio="16:9", duration=5)
        cdn_url = client.poll_until_complete(t_id)
        client.download_video(cdn_url, "seedance_render_output.mp4")
    except Exception as exc:
        logger.error(f"流水线执行失败: {exc}")

import axios, { AxiosInstance } from 'axios';

export interface SeedanceGenerateOptions {
  prompt: string;
  aspectRatio?: '16:9' | '9:16' | '1:1' | '4:3' | '21:9';
  duration?: 5 | 10;
  quality?: 'standard' | 'high';
  seed?: number;
  imageUrl?: string;
  webhookUrl?: string;
}

export interface TaskStatusResponse {
  taskId: string;
  status: 'QUEUED' | 'PROCESSING' | 'SUCCESS' | 'FAILED';
  progress?: number;
  videoUrl?: string;
  errorMessage?: string;
}

export class SeedanceVideoService {
  private client: AxiosInstance;

  constructor(apiKey?: string, baseURL = 'https://api.toapis.com/v1') {
    const token = apiKey || process.env.TOAPIS_API_KEY;
    if (!token) {
      throw new Error('缺失 TOAPIS_API_KEY 环境变量');
    }

    this.client = axios.create({
      baseURL,
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      timeout: 20000,
    });
  }

  /**
   * 提交 Seedance 2.0 视频生成任务
   */
  async submitTask(options: SeedanceGenerateOptions): Promise<string> {
    const payload = {
      model: 'doubao-seedance-2-0',
      prompt: options.prompt,
      aspect_ratio: options.aspectRatio || '16:9',
      duration: options.duration || 5,
      quality: options.quality || 'standard',
      seed: options.seed,
      image_url: options.imageUrl,
      webhook_url: options.webhookUrl,
    };

    const res = await this.client.post('/videos/generations', payload);
    const taskId = res.data?.data?.task_id;
    if (!taskId) {
      throw new Error('网关响应未返回有效的 task_id');
    }
    return taskId;
  }

  /**
   * 轮询任务状态直至完成或失败
   */
  async waitForCompletion(
    taskId: string,
    intervalMs = 3000,
    maxWaitMs = 180000
  ): Promise<string> {
    const startTime = Date.now();

    while (Date.now() - startTime < maxWaitMs) {
      await new Promise((resolve) => setTimeout(resolve, intervalMs));

      const res = await this.client.get('/tasks/video-status', {
        params: { task_id: taskId },
      });

      const data = res.data?.data;
      const status = data?.status;

      if (status === 'SUCCESS') {
        return data.video_url;
      }
      if (status === 'FAILED') {
        throw new Error(`Seedance 任务失败: ${data.error_message || '未知错误'}`);
      }
    }

    throw new Error(`Seedance 任务 ${taskId} 超过最大等待时间 (${maxWaitMs / 1000}秒)`);
  }
}

┌─────────────────────────────────────────────────────────────────────────────────┐
│ 轮询与 Webhook 架构决策选型对照表                                                │
├──────────────────┬─────────────────────────────┬────────────────────────────────┤
│ 评估维度         │ 客户端状态轮询 (/status)    │ Webhook 事件回调 (POST /hook)  │
├──────────────────┼─────────────────────────────┼────────────────────────────────┤
│ 适配日任务规模   │ < 500 条视频 / 天           │ > 500 条视频 / 天              │
│ 应用服务器开销   │ 较高 (单任务产生 10~20 次请求)│ 极低 (仅一次单向推送通知)      │
│ 网关 QPS 峰值负载│ 突发并发时显著升高          │ 几乎无额外轮询带宽开销         │
│ 网络环境要求     │ 支持内网 NAT / Localhost 本地│ 必须具备公网可访问 HTTPS 接口  │
│ 故障自愈能力     │ 循环内置重试逻辑            │ 需配置死信队列与幂等消费机制   │
└──────────────────┴─────────────────────────────┴────────────────────────────────┘

FALLBACK_CASCADE = [
    {"model": "doubao-seedance-2-0", "timeout_sec": 45},
    {"model": "kling-3-omni", "timeout_sec": 60},
    {"model": "minimax-h3", "timeout_sec": 45}
]