Ad Video Generator v3

1. 빠른 시작 (Quick Start)

3단계로 광고 영상을 만들 수 있습니다.

1

주제 입력 → AI 스크립트 생성 상단 AI Script Generator에 주제를 입력하고 AI Generate 클릭. Groq LLM이 제목·내레이션·이미지 프롬프트를 자동 작성합니다.

2

설정 확인 → (선택) 씬 수정 음성, 스타일, BGM, Ken Burns 효과를 설정합니다. 자동 생성된 씬을 수정하거나, 직접 이미지를 업로드할 수 있습니다.

3

Generate Video 클릭 영상 생성이 시작되면 Projects 탭에서 진행률을 실시간 확인할 수 있습니다. 완성 후 다운로드 또는 텔레그램 발행이 가능합니다.

평균 생성 시간: 씬 1개당 약 4~5초. 4개 씬 기준 약 15~20초면 1920×1080 Full HD 영상이 완성됩니다.

2. AI 스크립트 생성

Groq LLM (Llama 3.3-70B)이 주제만으로 전문 광고 스크립트를 자동 작성합니다.

사용 방법

AI Script Generator 영역에 주제를 입력합니다
Language를 먼저 선택하면, 해당 언어로 스크립트가 생성됩니다
AI Generate 버튼 클릭 → 3~5초 후 씬이 자동으로 채워집니다

입력 예시

주제 입력	생성 결과
UpFinance VISA 카드의 해외 결제 편리성	4개 씬: 해외 여행 장면, 결제 순간, 환율 혜택, CTA
비트코인 2026년 전망	4개 씬: 시장 분석, 기관 투자, 기술 발전, 투자 전략
AI fitness coaching app launch	4 scenes: Problem, Solution demo, Features, Download CTA

AI가 생성한 스크립트는 자유롭게 편집할 수 있습니다. 내레이션 문구를 수정하거나, 씬을 추가/삭제할 수 있습니다.

3. 씬(Scene) 편집

각 씬은 하나의 장면을 구성합니다. 영상은 씬 순서대로 연결됩니다.

씬 구성 요소

필드	설명	필수
Narration	TTS 음성으로 읽어줄 대사. 자막도 여기서 자동 생성됩니다.	필수
Image Prompt	배경 이미지를 설명하는 프롬프트. AI가 이미지를 생성하거나 Pexels에서 검색합니다.	선택
Upload Image	직접 이미지를 업로드. 업로드하면 Image Prompt보다 우선 적용됩니다.	선택

씬 조작

+ Add Scene — 새로운 빈 씬 추가 (최대 제한 없음, 권장 3~6개)
× 버튼 — 해당 씬 삭제 (최소 1개는 유지)
씬 순서 = 영상 재생 순서 (위에서 아래로)

Narration이 비어있는 씬은 영상 생성 시 자동으로 제외됩니다.

4. 이미지 소스 & 업로드

각 씬의 배경 이미지는 3단계 폴백 체인으로 결정됩니다.

Upload 이미지 → Gemini AI 생성 → Pexels 실사 검색 → Styled Placeholder

이미지 우선순위

순위	소스	설명
1순위	Upload	사용자가 직접 업로드한 이미지. JPG/PNG/WebP, 최대 10MB
2순위	Gemini AI	Image Prompt 기반 AI 이미지 생성 (Google Gemini API)
3순위	Pexels	Image Prompt 키워드로 무료 실사 이미지 자동 검색 (3,187만+ 사진)
4순위	Placeholder	스타일별 그라데이션 배경 + 텍스트 (항상 성공)

이미지 업로드 방법

각 씬의 Upload Image 영역을 클릭하거나 파일을 드래그앤드롭합니다
업로드 성공 시 미리보기와 파일명이 표시됩니다
업로드된 이미지가 있으면 Image Prompt는 무시됩니다

제품 사진, 로고, 실제 매장 사진 등을 업로드하면 더 실감나는 광고 영상을 만들 수 있습니다.

5. 음성 / 스타일 / 효과

음성 (Voice)

Microsoft Edge-TTS 엔진을 사용합니다. 별도 API 키 없이 무료로 고품질 음성을 제공합니다.

음성 ID	이름	언어	특징
edge-ko-female	Sun-Hi (한국어 여성)	Korean	자연스러운 한국어, 광고 내레이션에 적합
edge-ko-male	InJoon (한국어 남성)	Korean	신뢰감 있는 남성 음성
edge-en-female	Jenny (영어 여성)	English	밝고 명확한 영어 음성
edge-en-male	Guy (영어 남성)	English	전문적인 영어 내레이션
edge-ja-female	Nanami (일본어 여성)	Japanese	자연스러운 일본어
edge-zh-female	Xiaoxiao (중국어 여성)	Chinese	표준 중국어

영상 스타일

스타일	설명	추천 용도
Illustration	일러스트 느낌의 부드러운 이미지	교육, 설명 영상
Modern 3D	세련된 3D 렌더링 스타일	IT, 테크 제품
Tech Dark	다크 테마의 기술적 느낌	블록체인, AI, 핀테크
Premium Gold	골드 & 럭셔리 프리미엄	금융, 투자, 부동산
Anime	애니메이션 스타일	게임, 엔터테인먼트
Realistic	사실적 사진 스타일	실물 제품 광고
Minimal	미니멀 클린 디자인	SaaS, 앱 소개

BGM (배경 음악)

옵션	설명
None	배경 음악 없음 (내레이션만)
Ambient	잔잔한 환경 음악
Upbeat	활기찬 배경 음악
Corporate	기업 프레젠테이션 스타일

Ken Burns 효과

정지 이미지에 자연스러운 줌인/아웃 및 팬 효과를 적용합니다. 영상이 훨씬 역동적으로 보이도록 만들어주며, 기본적으로 활성화되어 있습니다.

6. TikTok 스타일 자막

v3에서 추가된 워드 레벨(Word-level) 자막은 각 단어에 타이밍을 맞춰 노란색 하이라이트를 표시합니다.

자막 구조 (3레이어)

레이어	스타일	역할
Layer 0	WordBg (배경)	전체 문장을 반투명 흰색으로 표시 — 읽기 가이드 역할
Layer 1	WordHi (하이라이트)	현재 읽히는 단어만 노란색 볼드체로 강조 표시

TTS 음성 생성 → 단어별 타이밍 추출 → ASS 자막 생성 → ffmpeg 자막 합성

TikTok, Instagram Reels에서 흔히 볼 수 있는 "가라오케" 스타일 자막입니다. 시청자의 집중도를 높여주며 음소거 환경에서도 내용 전달이 가능합니다.

7. 프로젝트 관리 & 다운로드

프로젝트 상태

상태	설명	가능한 작업
draft	생성 대기	Generate 버튼으로 생성 시작
processing	생성 중 (진행률 표시)	실시간 진행률 확인
completed	생성 완료	Download, Telegram 발행
error	오류 발생	Retry 버튼으로 재시도

다운로드

완성된 영상은 Download 버튼으로 MP4 파일을 직접 다운로드할 수 있습니다.

해상도: 1920×1080 (Full HD)
코덱: H.264 (MP4)
자막: ASS 방식으로 영상에 하드코딩됨

8. 멀티플랫폼 발행 & 봇 명령어

지원 플랫폼

플랫폼	상태	설명
Telegram	Ready	봇을 통한 채널/그룹 발행
Twitter/X	Ready	OAuth 1.0a 청크 업로드 + 트윗 게시
LinkedIn	Ready	Videos API + Posts API 연동
YouTube	Stub	OAuth 설정 필요
TikTok	Stub	OAuth 설정 필요
Instagram	Stub	Graph API 설정 필요
Facebook	Stub	Page API 설정 필요

웹에서 멀티플랫폼 발행

Projects 탭에서 완성된 영상의 Publish 버튼 클릭
발행할 플랫폼을 체크박스로 선택 (복수 선택 가능)
Telegram 선택 시 채널/그룹을 추가 선택
설명(description) 입력 (선택, Twitter/LinkedIn 캡션용)
PIN 입력 후 Publish 클릭 → 플랫폼별 결과 확인

텔레그램 봇 명령어 (/video)

명령어	설명	예시
/video <주제>	주제로 AI 영상 자동 생성 + 채팅방 업로드	/video 비트코인 2026년 전망
/video list	최근 10개 프로젝트 목록 조회	/video list
/video templates	사용 가능한 템플릿 목록	/video templates
/video status <id>	특정 프로젝트 상태 확인	/video status abc-123
/video publish <id>	Telegram에 영상 공유 (기본)	/video publish abc-123
/video publish <id> twitter,linkedin	지정 플랫폼에 발행	/video publish abc-123 twitter,linkedin
/video publish <id> all	Telegram + Twitter + LinkedIn 동시 발행	/video publish abc-123 all

자동 생성 흐름: /video 명령 → AI 스크립트 작성 → 프로젝트 생성 → 영상 생성 → 완성 후 자동 업로드 (약 30초~2분)

9. API 레퍼런스

외부 시스템에서 영상 생성을 자동화할 수 있는 REST API를 제공합니다.

Base URL: https://video.metaquant.club/api/ad-video

Method	Endpoint	설명
GET	/voices	사용 가능한 음성 목록
GET	/templates	템플릿 목록
GET	/projects	전체 프로젝트 목록
GET	/projects/:id	프로젝트 상세 정보
POST	/generate-script	AI 스크립트 생성
POST	/projects	프로젝트 생성
POST	/projects/:id/generate	영상 생성 시작
POST	/projects/:id/publish	멀티플랫폼 발행 (telegram/twitter/linkedin)
GET	/platforms	사용 가능한 플랫폼 목록 + 설정 상태
GET	/projects/:id/publish-history	프로젝트별 발행 이력 조회
POST	/upload-image	이미지 업로드 (multipart/form-data)
GET	/download/:id	완성 영상 다운로드 (MP4)

예시: curl로 영상 자동 생성

# 1. AI 스크립트 생성 curl -X POST https://video.metaquant.club/api/ad-video/generate-script \ -H "Content-Type: application/json" \ -d '{"topic":"비트코인 전망","language":"ko","scene_count":4}' # 2. 프로젝트 생성 curl -X POST https://video.metaquant.club/api/ad-video/projects \ -H "Content-Type: application/json" \ -d '{"title":"BTC 전망","style":"tech-dark","voice_id":"edge-ko-female", "scenes":[{"narration":"비트코인 시장을 분석합니다","image_prompt":"bitcoin chart"}]}' # 3. 영상 생성 시작 curl -X POST https://video.metaquant.club/api/ad-video/projects/{id}/generate # 4. 상태 확인 (polling) curl https://video.metaquant.club/api/ad-video/projects/{id} # 5. 다운로드 curl -O https://video.metaquant.club/api/ad-video/download/{id}

10. FAQ & 문제 해결

질문	답변
영상 생성에 실패합니다	Projects 탭에서 Retry 버튼으로 재시도하세요. 대부분 일시적인 API 오류이며 재시도하면 성공합니다.
이미지가 Placeholder로만 나옵니다	Gemini API와 Pexels API 모두 실패한 경우입니다. Image Prompt를 영어로 바꾸거나, 직접 이미지를 업로드해 보세요.
자막이 노란색으로 안 나옵니다	워드 레벨 자막은 Edge-TTS에서 타이밍 데이터를 받아야 합니다. TTS 엔진이 타이밍을 반환하지 않으면 기본 자막(흰색)으로 폴백합니다.
텔레그램 발행이 안 됩니다	영상 파일이 50MB를 초과하면 텔레그램 업로드가 실패할 수 있습니다. 씬 수를 줄여 짧은 영상으로 만들어 보세요.
영상 최대 길이는?	기술적 제한은 없으나, 광고 효과를 위해 15~60초(3~8씬) 이내를 권장합니다.
비용이 드나요?	TTS(Edge-TTS)와 이미지(Pexels)는 완전 무료입니다. Gemini AI 이미지 생성만 소량 비용이 발생하며, Pexels 폴백이 있어 무료로도 사용 가능합니다.
여러 언어를 섞어 쓸 수 있나요?	하나의 영상에서 음성 언어는 1개만 선택 가능합니다. 다국어 영상이 필요하면 각 언어별로 별도 프로젝트를 만들어 주세요.

Ad Video Generatorv3

Ad Video Generator v3 — 사용 설명서