Anil-matcha/Seedance-2-API

Python wrapper for ByteDance's Seedance 2.0 , Seedance 2.5 and Seedance 2 Mini API — Text-to-Video, Image-to-Video, realistic human faces, 1080p, consistent character generation.

개요

Seedance‑2‑API는 ByteDance의 Seedance 비디오 생성 모델(2.0, 2.5 및 최신 2 Mini)을 위한 Python 래퍼입니다. 이 래퍼는 공개된 MuAPI 엔드포인트와 통신하여 인증, 요청 형식 지정 및 결과 폴링을 처리합니다. 개발자는 텍스트 프롬프트에서 영화 같은 AI 비디오를 생성하고, 정지 이미지를 애니메이션화하며, 기존 클립을 편집하고, 여러 생성물에 걸쳐 캐릭터의 일관성을 유지할 수 있습니다.

라이브러리 기능

기능	설명
텍스트-비디오 (T2V)	자연어 프롬프트를 보내고 고품질 비디오(1080p, 2.5 버전은 4K)를 받습니다.
이미지-비디오 (I2V)	하나 이상의 참조 이미지를 제공하면 모델이 프롬프트에 따라 애니메이션화합니다.
옴니 참조 (Omni‑Reference)	이미지, 비디오, 오디오 참조를 단일 요청으로 결합하여 더 풍부한 조건 설정을 제공합니다.
캐릭터 시트 (Character Sheets)	1~3장의 사진에서 다각도 캐릭터 참조를 생성하고, 이후 프롬프트에서 `@character:<id>`를 사용하여 얼굴 일관성을 유지합니다.
비디오 편집 (Video‑Edit)	텍스트 설명과 선택적 참조 미디어를 사용하여 기존 비디오를 수정합니다.
Mini 모델	저비용, 고속 변형(Seedance 2 Mini)으로 별도의 SDK 호출(`text_to_video_mini`, `image_to_video_mini`)을 지원합니다.
MCP 서버	다른 AI 어시스턴트(Claude, Cursor 등)가 Seedance를 직접 호출할 수 있도록 하는 선택적 Model Context Protocol 서버입니다.
유틸리티 헬퍼	파일 업로드, 환경 변수 기반 API 키 처리, MuAPI 상태 엔드포인트를 폴링하는 `wait_for_completion` 헬퍼를 제공합니다.

시작하기

# PyPI에서 설치 (권장)
pip install seedance-2-api

.env 파일을 생성하고 MuAPI 키를 설정합니다:

MUAPI_API_KEY=your_muapi_api_key_here

기본 사용 예시(텍스트-비디오):

from seedance_api import SeedanceAPI
api = SeedanceAPI()
submission = api.text_to_video(
    prompt="A cinematic slow‑motion shot of a cyberpunk city in the rain, neon lights reflecting on puddles",
    aspect_ratio="16:9",
    duration=5,
    quality="high",
)
result = api.wait_for_completion(submission["request_id"])
print("Video URL:", result["url"])

동일한 패턴이 Mini 모델(text_to_video_mini)이나 이미지-비디오(image_to_video, image_to_video_mini)에도 적용됩니다.

핵심 개념

요청 ID (Request IDs) – 모든 MuAPI 호출은 request_id를 반환합니다. api.wait_for_completion(request_id)를 사용하여 비디오가 준비될 때까지 폴링합니다.
캐릭터 워크플로우 – 먼저 참조 사진으로 api.create_character(또는 api.character)를 호출하고 시트 생성을 기다린 후, 이후 프롬프트에서 @character:<request_id>를 통해 참조합니다.
MCP 서버 – python3 mcp_server.py를 실행하여 Model Context Protocol을 통해 래퍼를 노출하면, 다른 AI 도구가 HTTP 코드를 작성하지 않고도 Seedance를 호출할 수 있습니다.

이 라이브러리를 사용해야 하는 경우

자체 추론 스택을 구축하지 않고 고충실도 AI 비디오(1080p‑4K)가 필요한 경우.
여러 클립에서 캐릭터 일관성을 유지하는 것이 애플리케이션에 중요한 경우.
원시 curl 호출보다 간단한 Python 인터페이스를 선호하는 경우.
빠른 프로토타이핑이나 대규모 파이프라인을 위해 저비용 Mini 모델을 실험하고 싶은 경우.

제한 사항 및 고려 사항

이 라이브러리는 씬 클라이언트일 뿐이며, 모든 무거운 작업(모델 추론, 렌더링)은 MuAPI 서버에서 수행됩니다.
요청당 비용이 발생합니다(예: 캐릭터 시트는 $0.18, Mini 모델은 초당 약 $0.073). MuAPI 계정을 통해 사용량을 모니터링하십시오.
콘텐츠 정책은 일부 경쟁사보다 관대하지만, 여전히 MuAPI의 서비스 약관을 준수해야 합니다.

요약

seedance-2-api는 ByteDance의 Seedance 비디오 생성 모델을 위한 실무용 Python SDK입니다. MuAPI를 통해 텍스트-비디오, 이미지-비디오, 캐릭터 일관성, 비디오 편집 및 저비용 Mini 변형을 제공합니다. pip으로 설치하고 MuAPI 키를 설정한 뒤 고수준 메서드를 호출하기만 하면, 단 몇 줄의 코드로 영화 같은 AI 비디오를 생성할 수 있습니다.