비동기 Video Gen Client로 여러 AI 제공업체에서 동영상 생성

Video Gen Client의 기능

Video Gen Client는 여러 동영상 생성 제공업체를 위한 하나의 비동기 Python 클라이언트를 제공합니다. 지원 제공업체로는 ByteDance의 Seedance, Kuaishou의 Kling, MiniMax/Hailuo, Alibaba의 Wan이 있습니다. 각각 별도의 제공업체 통합을 사용하는 대신, 통합 명령줄 인터페이스 또는 웹 애플리케이션을 통해 사용 가능한 모델을 확인하고, 생성 작업을 제출하며, 상태를 확인하고, 결과를 다운로드할 수 있습니다.

이 프로젝트는 제공업체 API를 중심으로 작성된 통합 코드입니다. 해당 API와 모델 ID는 서로 독립적으로 변경될 수 있으므로 제공업체 어댑터를 시간이 지나면서 업데이트해야 할 수 있습니다.

지원 제공업체 및 모델

현재 클라이언트에는 다음 제공업체 제품군과 API 모델 ID가 등록되어 있습니다.

• Seedance: 버전 2.5는 doubao-seedance-2.5를 사용하고, 버전 2.0은 doubao-seedance-2-0-260128을 사용합니다. 2.0 Mini 및 2.0 Fast 등급은 각각 doubao-seedance-2-0-mini-260615과 doubao-seedance-2-0-fast-260128을 사용합니다.
• Kling: Kling 3.0과 3.0 Omni는 각각 kling-v3과 kling-v3-omni를 사용합니다. 그 밖에 등록된 모델로는 kling-v2-6, kling-v2-5-turbo, kling-v2-1-master가 있습니다.
• MiniMax/Hailuo: H3는 MiniMax-H3를 사용하고, 버전 2.3은 MiniMax-Hailuo-2.3과 MiniMax-Hailuo-2.3-Fast를 사용합니다.
• Wan: Wan 3.0은 wan3.0을 사용합니다. Wan 2.7, 2.6, 2.5는 텍스트-동영상, 이미지-동영상, 참조-동영상 또는 미리보기용 특화 모델 ID를 제공합니다.

클라이언트 설치 및 구성

1. 저장소 복제:

   git clone https://github.com/letorig/video-generator-client
   cd video-generator-client

2. 가상 환경 생성:

   python -m venv .venv

3. 환경 활성화. Windows에서는 다음을 실행합니다:

   .venv\Scripts\activate

   macOS 또는 Linux에서는 다음을 실행합니다:

   source .venv/bin/activate

4. 웹 지원과 함께 패키지 설치:

   pip install -e ".[web]"

5. 제공업체 인증 정보 추가: .env.example을 .env로 복사한 다음, 사용할 제공업체의 인증 정보를 추가합니다. README에서는 하나의 인증 정보 세트를 지정하지 않으므로, 현재 작업 흐름에 필요한 서비스만 구성하세요.

CLI를 사용할 때 생성된 출력은 output 폴더에 저장됩니다.

명령줄 인터페이스 사용

설치 후 video-gen 명령은 제공업체 확인, 모델 선택, 생성 작업 시작, 결과 확인을 위한 기본 작업 흐름을 제공합니다.

제공업체 및 모델 확인

먼저 사용 가능한 명령과 제공업체를 확인합니다.

video-gen --help
video-gen providers

특정 제공업체의 모델을 확인하려면 models 명령에 해당 제공업체 이름을 전달합니다.

video-gen models wan

동영상 생성

프롬프트, 제공업체, 모델, 재생 시간을 지정하여 텍스트-동영상 요청을 제출합니다.

video-gen generate wan --prompt "A snowy forest at dawn" --model 2.1 --duration 5

이 명령은 선택한 제공업체를 통해 작업을 제출하고 결과를 output 폴더에 저장합니다. 제공업체별 모델 가용성은 변경될 수 있으므로, 직접 명령을 작성할 때는 프로젝트에서 제공하는 제공업체 및 모델 값을 사용하세요.

작업 상태 확인

비동기 생성 작업에서는 제공업체와 작업 ID를 사용하여 작업을 조회합니다.

video-gen status wan TASK_ID

TASK_ID를 생성 작업에서 반환된 식별자로 바꾸세요.

웹 인터페이스 실행

이 프로젝트에는 Python 패키지에 웹 인터페이스가 직접 포함되어 있습니다. npm, Node.js 또는 별도의 프런트엔드 빌드 단계가 필요하지 않습니다. FastAPI가 HTML 인터페이스를 제공하고 제공업체 확인, 동영상 생성, 작업 폴링, MP4 다운로드를 위한 JSON 엔드포인트를 노출합니다.

기본 호스트와 포트로 서버를 시작합니다.

video-gen serve

호스트와 포트를 명시적으로 지정할 수도 있습니다.

video-gen serve --host 127.0.0.1 --port 8000

자동 리로드를 활성화한 서버를 실행하려면 다음을 사용합니다.

video-gen serve --host 0.0.0.0 --port 9000 --reload

웹 UI 기능

이 인터페이스는 제공업체 및 모델 선택, 텍스트-동영상 및 이미지-동영상 입력, 네거티브 프롬프트, 재생 시간, 화면 비율, 해상도 제어를 지원합니다. 또한 실시간 작업 상태 폴링, 동영상 미리보기, MP4 다운로드, 현재 서버 세션의 메모리 내 작업 기록을 제공합니다.

실용적인 작업 흐름 팁

• 생성 전에 확인: 제공업체나 모델을 선택하기 전에 video-gen providers와 video-gen models PROVIDER를 실행하세요.
• 인증 정보 범위 제한: 현재 작업 흐름에 필요한 제공업체의 인증 정보만 .env 파일에 추가하세요.
• 비동기 작업 추적 사용: status 명령과 웹 인터페이스의 실시간 폴링으로 생성을 모니터링할 수 있습니다.
• 작업 흐름에 맞는 인터페이스 선택: CLI는 스크립트와 터미널 기반 작업에 편리하고, 웹 UI는 대화형 제어 기능과 미리보기를 제공합니다.
• 통합 유지 관리 고려: 제공업체 API와 모델 ID는 이 SDK와 독립적이며 변경될 수 있습니다. 따라서 제공업체가 서비스를 업데이트하면 어댑터와 모델 카탈로그를 확인하세요.

프로젝트 구조

저장소는 클라이언트, 명령줄 인터페이스, 웹 서버, 모델 카탈로그, 제공업체 어댑터, 정적 웹 자산, 예제, 테스트 및 유틸리티 코드를 분리합니다.

src/video_gen/
├── client.py
├── cli.py
├── web.py
├── catalog.py
├── static/index.html
├── providers/
└── utils/

구성은 .env.example로 관리하며, 패키징 및 설치 설정은 pyproject.toml에 정의되어 있습니다. 저장소에는 examples/, tests/, 선택 사항인 mcp_server/ 디렉터리도 포함되어 있습니다.

결론

Video Gen Client는 Python 개발자가 여러 비디오 생성 공급자를 통합된 방식으로 사용할 수 있도록 합니다. 가상 환경에 설치하고 필요한 자격 증명을 구성한 다음, 지원되는 모델을 확인하고 CLI 또는 포함된 FastAPI 웹 UI를 통해 작업을 제출할 수 있습니다. 프로덕션 환경에서는 모델 ID와 API 동작이 클라이언트와 독립적으로 변경될 수 있으므로 공급자 변경 사항을 모니터링해야 합니다.