VoxFlow 비디오 스킬
AI로 숏폼 비디오를 생성하세요: LLM이 대본을 작성하고, AI가 카드 또는 씬을 그리고, TTS가 나레이션을 제공하며, FFmpeg / Remotion이 최종 MP4를 렌더링합니다.
기사-카드 릴(슬라이스 – 13가지 테마: paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric)의 경우 voxflow:slice로 전환하세요. 공유 가능한 HTML/CSS 카드 이미지 세트 또는 나레이션 카드-투-MP4 내보내기의 경우 voxflow:card로 전환하세요.
다섯 가지 진입점 – 사용자가 원하는 것에 따라 선택하세요:
| 명령 | 출력 | 사용 시기 |
|---|---|---|
picstory | 세로/가로 MP4, 손그림 카드 또는 영화 같은 씬 | "지식 카드 비디오", 小红书 / Twitter 교육, 스케치노트 튜토리얼 |
present | 1080×1920 나레이션 카드 비디오, 5가지 비주얼 스킴 | 피치 데크, 설명 릴, 브랜드 숏폼 |
explain | 제목 / 불렛 / 요약 씬이 포함된 MP4 설명 영상 | "X가 무엇인가요?" 튜토리얼, 코스 소개 |
slides | 내장 TTS 오디오가 포함된 자체 완결형 HTML 데크 | 제품 출시, 강연, 링크로 공유 |
image | 단일 PNG | 일회성 일러스트 / 썸네일 (Hunyuan TextToImage) |
전제 조건
npm install -g voxflow및voxflow loginffmpeg설치 (brew install ffmpeg/sudo apt install ffmpeg) – MP4 렌더링에 필요present/explain(Remotion 기반)의 경우: 로컬 플러그인 설치 시remotion-cards/가 포함됩니다.present에서 "Remotion not ready"라고 표시되면 번들된remotion-cards/디렉토리 내에서npm install을 실행하세요.explain의 경우--cloud로 로컬 Remotion을 건너뛸 수 있습니다.
🎴 picstory — 지식 카드 비디오
LLM이 구조화된 대본을 작성하고, AI가 씬별로 하나의 카드를 그리고, TTS가 나레이션을 제공하며, FFmpeg가 조합합니다. 小红书 / Twitter 교육 / TikTok에 최적입니다.
빠른 시작
# 기본: 중국어, 스케치노트 스타일, 세로형, 5개 씬
voxflow picstory --topic "AI Agent 入门指南"
# 2개 씬 빠른 테스트 (전체 비디오 렌더링 없음)
voxflow picstory --topic "AI 入门" --scenes 2 --image-only
# 영어 가로 비디오
voxflow picstory --topic "How React Hooks Work" --language en --ratio landscape --style photo
출력: picstory-<timestamp>.mp4 + .json (대본).
카드형 스타일 (구조화된 제목 + 핵심 포인트)
--style | 느낌 | 최적 대상 |
|---|---|---|
sketchnote (기본값) | 다채로운 손그림 불렛 저널 | 지식 공유, 튜토리얼 |
neon_noir | 사이버펑크 느낌, 네온 발광 | 기술, 스타트업 |
minimal_3d | 파스텔 그라데이션 위 부드러운 3D 점토 | 小红书 라이프스타일 |
chalkboard | 진한 녹색 바탕의 흰색 분필 | 과학, 학술 |
씬형 스타일 (자유형 일러스트)
--style | 느낌 | 최적 대상 |
|---|---|---|
photo | 영화 같은 / 포토리얼 | 스토리텔링, 여행 |
manga_panel | 일본 만화 잉크 선화 | 드라마, 단계별 가이드 |
vintage_newspaper | 1940년대 타블로이드 | 역사, 사실적 스토리 |
비율
--ratio | 픽셀 | 플랫폼 |
|---|---|---|
portrait (기본값) | 1080×1920 | 小红书, TikTok, Reels, 抖音 |
landscape | 1920×1080 | YouTube, B站 |
square | 1080×1080 | Instagram, Twitter |
대본 모델 프리셋 (--script-model)
| 프리셋 | 제공자 | 강점 |
|---|---|---|
| 생략 | 서버 설정 | 균형 잡힌 기본값 (gpt-4o-mini) |
gemini-flash | OpenRouter | 다국어, 좋은 중국어 |
deepseek | DeepSeek | 가장 저렴, 탁월한 중국어 |
hunyuan | 腾讯混元 | 중국어 네이티브 |
moonshot | Moonshot | 중국어 긴 컨텍스트 |
서버는 허용 목록을 적용합니다 – 위의 프리셋 이름만 작동하며, 임의의 모델 ID는 거부됩니다.
이미지 품질 (--quality)
이미지 생성이 유일한 주요 비용입니다 (~이미지당 $0.005-0.08). LLM 대본 (~2K 토큰)은 무시할 수 있습니다.
--quality | 제공자 | 강점 | 이미지 5장 비용 |
|---|---|---|---|
fast (기본값) | OpenRouter Gemini Flash | 가장 저렴, 균형 잡힘 | ~$0.025 |
hd | OpenRouter Gemini Pro | 더 높은 디테일 | 중간 |
ultra | OpenRouter gpt-5.4-image-2 | 전반적으로 최고, ~16배 비용 | ~$0.40 |
fast-aiberm | Aiberm Gemini Flash | 저렴한 Aiberm 티어 | 낮음 |
hd-aiberm | Aiberm Gemini Pro | 가장 강력한 중국어 텍스트 렌더링 – 중국어 제목이 있는 小红书 카드에 최적 | 중간 |
반복에는 fast를, 카드에 정확한 중국어 문자가 필요한 경우 hd-aiberm을, 최종 출력에는 ultra를 사용하세요.
전체 옵션
| 플래그 | 기본값 | 설명 |
|---|---|---|
--topic <text> | 필수 (--text 또는) | 스토리 주제 |
--text <content> | — | 주제 대신 전체 기사 붙여넣기 |
--style <name> | sketchnote | 위 스타일 참조 |
--ratio <name> | portrait | portrait | landscape | square |
--language <code> | zh | zh | en | ja | ko | ... |
--scenes <n> | 5 | 2–10. 빠른 테스트에는 2 사용 |
--script-model <preset> | 서버 기본값 | 위 프리셋 참조 |
--quality <tier> | fast | 위 표 참조 |
--voice <id> | 기본값 | voxflow voices의 TTS 음성 |
--speed <n> | 1.0 | TTS 속도 0.5–2.0 |
--bgm <file> | — | 나레이션 아래에 혼합되는 배경 음악 (mp3/wav) |
--bgm-volume <n> | 0.1 | BGM 볼륨 0–1 |
--fade <n> | 0.4 | 씬당 페이드 인/아웃 시간 (초) (0으로 비활성화) |
--image-only | false | 최종 비디오 렌더링 없이 이미지 + 오디오 저장 |
--output-dir <dir> | — | 모든 출력에 대한 디렉토리 |
--output <path> | 자동 | 최종 MP4 경로 |
할당량 비용
| 작업 | 할당량 |
|---|---|
| LLM 대본 | 100 |
| TTS / 씬 | 50 |
| 이미지 / 씬 | 500 |
| 2개 씬 테스트 | ~1,200 |
| 5개 씬 전체 | ~2,850 |
무료 티어 (월 10K) ≈ picstory 비디오 3개 전체.
파이프라인
주제 / 텍스트
├─[1] LLM 대본 → { title, scenes: [{ heading, keyPoints, narration }] }
├─[2] 씬별 TTS → PCM 오디오
├─[3] 씬별 이미지 (병렬) → /api/image/generate를 통해 JPEG
└─[4] FFmpeg: 이미지 + WAV → Ken Burns zoompan MP4 → 연결 → +BGM → 최종.mp4
문제 해결
| 문제 | 해결책 |
|---|---|
ffmpeg not found | brew install ffmpeg (mac) / sudo apt install ffmpeg |
Image generation failed | 재시도; hd에서 멈추면 --quality fast로 낮추기 |
| 렌더링이 너무 느림 | Ken Burns는 CPU 집약적입니다. 먼저 --scenes 2 --image-only로 콘텐츠를 검증하세요. |
model_not_allowed | 원시 모델 ID 대신 --script-model 프리셋 이름 사용 |
| 카드에서 중국어 텍스트 깨짐 | --quality hd-aiberm으로 전환 |
📑 present — 나레이션 카드 비디오 (Remotion 로컬)
텍스트 또는 URL → LLM 카드 → TTS → Remotion 렌더링. 1080×1920, 5가지 비주얼 스킴.
voxflow present --text "Claude Code 是一个 AI 编程工具" --style aurora
voxflow present --url https://example.com/article --style noir
voxflow present --text "2025 AI 芯片格局" --web-search --style neon
voxflow present --cards pre-generated.json --no-audio
| 플래그 | 기본값 | 참고 |
|---|---|---|
--text / --url / --cards | 하나 필수 | 입력 소스 |
--style | aurora | noir | neon | editorial | aurora | brutalist |
--voice <id> | v-female-R2s4N9qJ | TTS 음성 |
--speed <n> | 1.0 | 0.5–2.0 |
--no-audio | false | 무음 비디오만 |
--web-search | false | 최신 웹 정보로 LLM 보강 |
--output <path> | ./present-<ts>.mp4 | .mp4 또는 .wav |
present가 "Remotion not ready"라고 보고하면 번들된remotion-cards/디렉토리 내에서npm install을 실행하여 로컬 렌더러를 설정하세요.
🧠 explain — AI 설명 영상
제목 / 불렛 / 요약 장면 흐름. "X가 무엇인가요?" 튜토리얼에 적합합니다.
voxflow explain --topic "What is React?"
voxflow explain --topic demo --output demo.mp4 # 내장 데모 (API 호출 없음)
voxflow explain --topic "区块链入门" --style chalkboard --voice v-male-Bk7vD3xP
voxflow explain --topic "Machine Learning" --audio-only
voxflow explain --topic "AI Agent 入门" --cloud # 서버에서 렌더링
| 플래그 | 기본값 | 참고 |
|---|---|---|
--topic <text> | 필수 | 내장 데모 대본에는 demo 사용 |
--style | modern | modern | playful | corporate | chalkboard |
--language | en | en | zh | ja | ko | ... |
--voice <id> | v-female-R2s4N9qJ | |
--scenes <n> | 5 | 3–12 |
--audio-only | false | 렌더링 건너뛰고 WAV만 출력 |
--cloud | false | 로컬 대신 클라우드 Remotion 사용 |
--output <path> | ./explain-<ts>.mp4 |
📊 slides — TTS가 포함된 HTML 프레젠테이션
슬라이드당 base64 오디오가 포함된 자체 완결형 HTML 데크를 생성합니다. 브라우저에서 열기만 하면 되며 서버가 필요 없습니다.
voxflow slides "AI in Healthcare"
voxflow slides "Q4 Revenue Report" --template report --theme paper
voxflow slides "React Tutorial" --template tutorial --model balanced
voxflow slides "Startup Pitch" --template pitch --theme ocean --no-audio
| 플래그 | 기본값 | 참고 |
|---|---|---|
--text <text> (또는 위치 인수) | 필수 | 주제 |
--template | free | product | report | tutorial | pitch | free |
--theme | midnight | midnight | paper | ember | forest | ocean |
--model | swift | swift | balanced | pro | creative |
--voice <id> | v-female-R2s4N9qJ | |
--no-audio | false | TTS 건너뛰기, 슬라이드만 |
--output <path> | ./slides-<ts>.html |
10가지 레이아웃: hero, title-bullets, two-column, three-cards, image-left, image-right, quote, timeline, stats, section. 템플릿은 자동으로 레이아웃 시퀀스를 선택합니다.
🖼 image — 단일 Hunyuan 일러스트
동기식 텍스트 → 이미지 (PNG). 썸네일 또는 일회성 아트에 유용합니다.
voxflow image "햇살이 들어오는 창가에서 자는 고양이" --resolution 1024:1024 -o cat.png
해상도: 768:768, 768:1024, 1024:768, 1024:1024, 720:1280, 1280:720, 768:1280, 1280:768, 1080:1920, 1920:1080.
프롬프트 최대 1000자. 출력: 로컬 PNG + COS URL.
올바른 도구 선택 체크리스트
"小红书 스타일 지식 카드" → picstory
"AI 숏폼 + 캡션" → picstory --style sketchnote
"설명 영상 / What is X?" → explain
"텍스트가 있는 브랜드 숏폼" → present
"이미 카드/대본이 있음" → present --cards
"오디오가 포함된 공유 가능한 HTML 데크" → slides
"단일 일러스트" → image
규칙
- 음성 검색은
--voice를 전달하기 전에voxflow voices로 하세요. ID를 추측하지 마세요. - 비디오 호출 전 할당량 확인 (
voxflow status): picstory ≈ 3K, present/explain ≈ 500–2K. - 먼저 저렴하게 테스트:
picstory --scenes 2 --image-only는 전체 렌더링 비용을 지불하기 전에 대본을 검증합니다. - 렌더링이 완료된 후 자동 재생:
open output.mp4(macOS).