AI 영상 생성
텍스트-투-비디오 / 이미지-투-비디오 / 디지털 휴먼 첫 프레임 구동.
shared/scripts/ai_video.py를 캡슐화하며, 플러그형 프로바이더, 비동기 제출→폴링→다운로드 방식. 사용자가 API 키를 직접 준비 (.env에 설정).
사전 준비: API 키 설정
설정 확인 경로 철칙: 먼저
cd로AGENTS.md끝에 명시된 Easel 프로젝트 루트로 이동하고, 현재 디렉토리에.env와skills/shared/scripts/가 있는지 확인한 후 레지스트리,check또는 생성 명령을 실행합니다. 워크스페이스의./shared/scripts/...를 사용하거나env/printenv에 변수가 표시되지 않는다는 이유로 설정되지 않았다고 판단하지 마십시오.
먼저 프로바이더를 선택하고 .env에 해당 키를 입력한 후, check로 오프라인 검증을 수행합니다:
python skills/shared/scripts/ai_video.py check --provider dashscope
| 프로바이더 | 서비스 | .env에 설정해야 할 항목 |
|---|---|---|
dashscope | 알리바바 통의완상 Wan | DASHSCOPE_API_KEY (선택 사항: DASHSCOPE_VIDEO_MODEL/DASHSCOPE_BASE_URL; 이전 이름 DASHSCOPE_MODEL 호환) |
ark | 볼크엔진 Seedance | ARK_API_KEY (선택 사항: ARK_MODEL/ARK_BASE_URL) |
kling | 쾌수 컬링 | KLING_ACCESS_KEY + KLING_SECRET_KEY (JWT 인증) |
openai-compatible | 범용 /videos 엔드포인트 | VIDEO_API_KEY + VIDEO_BASE_URL (선택 사항: VIDEO_MODEL) |
xhs-maas | 샤오홍슈 내부망 MaaS (happyhorse 텍스트/이미지-투-비디오) | XHS_MAAS_API_KEY (선택 사항: XHS_MAAS_VIDEO_BASE/XHS_MAAS_T2V_MODEL/XHS_MAAS_I2V_MODEL). DashScope 스타일 비동기 + api-key 헤더, 내부망 직접 연결 |
agnes | Agnes (agnes-video-2.5-flash) | AGNES_API_KEY (선택 사항: AGNES_BASE_URL/AGNES_MODEL/AGNES_SIZE). OpenAI Videos 호환 생성 + 커스텀 엔드포인트 폴링; 기본적으로 네이티브 오디오 포함 (프롬프트에서 사운드 설명); 외부망은 프록시 사용 |
또한 VIDEO_PROVIDER를 설정하면 매번 --provider를 입력하지 않아도 됩니다.
실행 전에 model_registry.py configured --group video --env-file .env를 먼저 실행하세요: 사용 가능한 프로바이더가 하나뿐이면 명시적으로 선택하고, 여러 개 있고 사용자가 특정 프로바이더를 지정하지 않은 경우, 기본값으로 임의로 선택하지 말고 프로바이더/모델 목록을 보여주고 이번에 사용할 것을 물어보세요.
입력
화면 비율 확인 필수: 사용자나 상위 작업이 가로/세로(또는 16:9/9:16/특정 비율)를 명확히 지정하지 않은 경우, 생성 또는 유료 호출 전에 반드시 질문하고 확인을 기다려야 합니다. 플랫폼, 프로필 또는 스크립트 기본값에서 묵시적으로 추론하지 마십시오. 이미 명확히 지정된 경우에는 반복해서 묻지 않습니다.
- 텍스트-투-비디오: 장면/카메라 움직임/스타일 설명(프롬프트)
- 이미지-투-비디오: 입력 이미지 하나(로컬 경로 또는 URL) + 선택적 움직임 설명
- 선택 사항: 길이
--duration, 화면 비율--ratio(16:9 / 9:16 / 1:1), 모델--model, 네이티브 오디오--audio auto|on|off
출력
생성된 비디오 파일; 반드시 -o를 사용하여 outputs/주제명/ 경로를 지정해야 합니다. 비동기 작업은 완료 시까지 자동으로 폴링한 후 다운로드합니다.
실행 단계
- 설정 및 기능 확인: 먼저
check를 실행한 후,capabilities --provider <p> --model <m>을 실행합니다. 단편 애니메이션의 경우 브랜드 이름만으로 모델이 네이티브 오디오를 지원하는지 추측하지 마십시오. 새 모델은VIDEO_CAPABILITIES_JSON에 기능과 요청 필드를 등록하며, 호출 흐름을 수정할 필요가 없습니다.probe-dialogue(단편 애니메이션용): 실제로 생성 1회 + ASR을 수행하여 해당 모델이 지정된 대사를 단어 단위로 충실하게 말할 수 있는지 테스트하고,dialogue_faithful을 판별하여 캐시합니다. 단편 애니메이션은 이를 기반으로 네이티브 대화를 사용할지, "대사 없는 생성 + 후반 더빙"을 사용할지 결정합니다. 사용법:probe-dialogue --provider <p> --model <m>.
- 프롬프트 작성: AI 비디오는 프롬프트에 민감하므로, AI 비디오 프롬프트 가이드라인에 따라 구도, 카메라 움직임, 스타일 및 길이를 작성합니다. 세로형 숏폼 비디오는
--ratio 9:16을 사용합니다. - 텍스트-투-비디오:
python skills/shared/scripts/ai_video.py text2video --provider dashscope \ --prompt "해변 일몰, 느린 클로즈업, 따뜻한 톤, 영화 같은 느낌" --ratio 9:16 --duration 5 \ --audio auto \ -o outputs/주제명/clip.mp4 - 이미지-투-비디오 / 이미지 움직이기 / 디지털 휴먼 첫 프레임:
python skills/shared/scripts/ai_video.py image2video --provider kling \ --image outputs/주제명/cover.png --prompt "인물이 미소 지으며 손을 흔들고, 머리카락이 살짝 흔들림" \ -o outputs/주제명/clip.mp4 - 후속 가공: 생성된 클립은
video_ops.py(이어붙이기/자막 추가/BGM 추가/가로세로 변환),auto-subtitle(자막),tts-voiceover(더빙)에 전달하여 최종 영상으로 조합하거나,auto-short-video종단 간 워크플로우에 직접 투입할 수 있습니다.
프로필 인식
- 프로필 있음:
style.md에서 시각적 스타일 선호도를 가져와 프롬프트에 주입;platforms.md는 화면 비율 제안에만 사용되며, 사용자 확인을 대체할 수 없습니다. - 프로필 없음: 먼저 가로/세로를 확인한 후, 확인된 비율에 따라 생성합니다.
주의 사항
- 비디오 생성 API는 모두 비동기이며 시간이 많이 소요되고 (수십 초에서 수 분) 사용량에 따라 과금되므로, 먼저 사용자와 확인하세요.
- 각 프로바이더의 모델명/필드는 버전에 따라 다를 수 있으며,
--model또는 환경 변수로 재정의할 수 있습니다. 오류 발생 시 공식 최신 문서를 참조하여 조정하세요. --audio auto는 기능 프로필에 따라 알려진 필드만 매핑합니다. 기능 선언이 품질을 보장하지는 않으므로, 다운로드 후에도 ffprobe/ASR/시각 감사를 수행해야 합니다. 게이트웨이에 기본적으로 오디오가 있지만 on/off 필드를 모르는 경우, 매개변수를 추측하여 주입하지 마십시오.