┌─────────────────┐             ┌─────────────────────┐             ┌─────────────────────────┐
│ 클라이언트 앱   │             │ ToAPIs 통합 게이트웨이 │             │ ByteDance GPU 클러스터  │
│ (백엔드 서비스) │             │ (api.toapis.com)    │             │ (Seedance 2.0 엔진)     │
└────────┬────────┘             └──────────┬──────────┘             └────────────┬────────────┘
         │                                 │                                     │
         │ 1. POST /v1/videos/generations  │                                     │
         │────────────────────────────────>│ 2. 토큰 검증 & 작업 큐 등록         │
         │                                 │────────────────────────────────────>│
         │ 3. HTTP 202: task_id 반환       │                                     │
         │<────────────────────────────────│                                     │
         │                                 │                                     │
         │ 4. GET /v1/tasks/video-status   │                                     │
         │    (3초 대기 후 폴링)           │                                     │
         │────────────────────────────────>│ 5. 대기열 상태 및 진행률 확인       │
         │                                 │────────────────────────────────────>│
         │ 6. 진행 상태: "PROCESSING" (35%)│<────────────────────────────────────│
         │<────────────────────────────────│                                     │
         │                                 │                                     │
         │ 7. GET /v1/tasks/video-status   │                                     │
         │    (3초 대기 후 폴링)           │                                     │
         │────────────────────────────────>│ 8. 렌더링 완료, CDN 배치 완료       │
         │                                 │────────────────────────────────────>│
         │ 9. 완료 응답: "SUCCESS" + MP4 URL│<───────────────────────────────────│
         │<────────────────────────────────│                                     │
         │                                 │                                     │
         │ 10. 자체 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"

"""
ToAPIs 게이트웨이를 통한 Seedance 2.0 Video API 프로덕션 클라이언트
핵심 기능:
- 타입 안전한 요청 페이로드 구성
- 타임아웃 안전장치를 갖춘 지능형 상태 폴링
- 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 키가 없습니다. 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:
        """비디오 생성 작업을 제출하고 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을 반환합니다"""
        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}초 경과] 상태: {status} ({progress}%)")

            if status == "SUCCESS":
                video_url = body.get("video_url")
                if not video_url:
                    raise SeedanceAPIError("작업이 SUCCESS이나 video_url이 없습니다.")
                logger.info(f"비디오 생성 완료! 소요시간: {elapsed}초, URL: {video_url}")
                return video_url
            elif status in ("FAILED", "CANCELED"):
                error_msg = body.get("error_message", "알 수 없는 렌더링 오류")
                raise SeedanceAPIError(f"작업 {task_id} 실패: {error_msg}")

        raise TimeoutError(f"작업 {task_id}이 최대 타임아웃({max_timeout}초)을 초과했습니다.")

    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()
    test_prompt = "클로즈업 매크로 촬영: 정밀한 스틸 기어 금형에 부어지는 녹은 구리 액체, 튀는 불꽃, 어두운 기계 공방 분위기, 레이트레이싱 반사광, 1080p 30fps"
    
    try:
        t_id = client.submit_video_task(prompt=test_prompt, aspect_ratio="16:9", duration=5)
        v_url = client.poll_until_complete(t_id)
        client.download_video(v_url, "seedance_gear_korea.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(`작업 ${taskId}이 대기 시간(${maxWaitMs / 1000}초)을 초과했습니다.`);
  }
}

┌─────────────────────────────────────────────────────────────────────────────────┐
│ 폴링 vs 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}
]