TL;DR

이 레포지토리는 독립 CLI나 라이브러리가 아니라 Next.js 기반의 AI 영상 제작 SaaS 웹 애플리케이션입니다. 사용자의 스토리 프롬프트를 구조화된 스크립트로 바꾸고 캐릭터, 분镜图, 장면 영상, 최종 합성 영상을 다섯 단계로 생성합니다. 병렬 생성, 중단·재개, 버전 관리, 프로젝트·소재库 저장을 제공해 반복 제작 흐름을 관리합니다. Kie.ai, ZenMux, PostgreSQL, Stripe, OAuth 등 외부 의존성이 많으므로 바로 기능을 가져다 쓰기보다 자체 AI 영상 서비스의 기반 코드로 검토하는 편이 적합합니다.

핵심 포인트

• Magiviz는 Next.js와 TypeScript로 구축한 AI 영상 제작 웹 애플리케이션으로, CLI나 독립 라이브러리보다 배포 가능한 SaaS 템플릿에 가깝습니다. 사용자가 프롬프트와 영상 설정을 입력하면 AI剧情生成, 캐릭터 이미지 생성, 분镜图 생성, 장면 영상 생성, 전체 영상 합성을 순서대로 실행합니다. Veo, Kling, Seedance, Wan 등 여러 영상 생성 모델을 Kie.ai를 통해 연결하므로 모델별 API를 직접 통합하는 작업을 줄일 수 있습니다.
• 핵심 워크플로는 `components/operate.tsx`의 `AIFunction` 컴포넌트가 상태 머신으로 관리하며, 스토리 생성 이후 캐릭터·분镜图·장면 영상 단계는 병렬 처리를 사용합니다. 각 단계는 진행 중인 비동기 작업을 기다린 뒤 중단하거나, `resumeProjectId`와 `resumeVersionId`를 이용해 완료된 단계 다음부터 재개할 수 있습니다. 생성 실패 시 요소별 오류 상태를 표시하고 단일 캐릭터나 분镜图만 다시 생성할 수 있어 반복 제작 과정에서 전체 파이프라인을 매번 다시 실행하지 않아도 됩니다.
• 프로젝트와 결과물은 PostgreSQL과 Drizzle ORM에 저장되며, `versionGroupId`와 `version`으로 재생성 이력과 활성 버전을 분리합니다. 프로젝트 상세 화면은 스크립트, 캐릭터, 분镜图, 장면 영상, 최종 영상, 과거 버전을 탭으로 나누고 JSON·PNG·MP4 다운로드를 제공합니다. 소재库는 업로드 파일, 저장 공간, 프로젝트 참조 관계를 관리하므로 단순 생성 데모보다 장기적인 콘텐츠 관리 기능에 초점을 둔 구조입니다.
• 실행에는 Node.js 18+, PostgreSQL, Kie.ai API Key, ZenMux API Key가 필요하고, 사용자 인증·Stripe 결제·Resend 이메일·Pusher 실시간 업데이트까지 여러 외부 서비스가 포함됩니다. `npm install`, 환경 변수 설정, `npm run db:push`, `npm run dev` 순서로 로컬 실행이 가능하며 Vercel 배포를 권장합니다. 따라서 영상 생성 서비스의 출발점이나 상용 SaaS 프로토타입에는 적합하지만, 외부 API 비용과 인증·결제·웹훅 설정까지 직접 운영할 계획이 없다면 도입 부담이 큽니다.