| name | video |
| description | Use when the user wants AI-generated short-form video — knowledge cards (picstory / 小红书 / TikTok / Reels), narrated explainers, presentations, AI clips, or slides — covering picstory, present, slides, explain, and image generation. For article-to-card reels (Slice — 13 themes including paper-slide), use voxflow:slice. For shareable HTML/CSS card images or narrated card MP4 videos (`voxflow card render`) use voxflow:card. |
VoxFlow Video Skill
Generate short-form videos with AI: LLM writes the script, AI draws cards or scenes, TTS narrates, FFmpeg / Remotion renders the final MP4.
For article-to-card reels (Slice — 13 themes: paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric), switch to voxflow:slice. For shareable HTML/CSS card image sets or narrated card-to-MP4 export, switch to voxflow:card.
Five entry points — pick by what the user wants:
| Command | Output | Use when |
|---|
picstory | Vertical/landscape MP4 with hand-drawn cards or cinematic scenes | "知识卡片视频", 小红书 / Twitter edu, sketchnote tutorials |
present | 1080×1920 narrated card video, 5 visual schemes | Pitch decks, explainer reels, branded short-form |
explain | MP4 explainer with title / bullets / summary scenes | "What is X?" tutorials, course intros |
slides | Self-contained HTML deck with embedded TTS audio | Product launches, talks, share-as-link |
image | Single PNG | One-off illustrations / thumbnails (Hunyuan TextToImage) |
Prerequisites
npm install -g voxflow and voxflow loginffmpeg installed (brew install ffmpeg / sudo apt install ffmpeg) — required for MP4 render- For
present / explain (Remotion-backed): the local plugin install includes remotion-cards/. If present says "Remotion not ready", run npm install inside the bundled remotion-cards/ directory. For explain, you can skip local Remotion with --cloud.
🎴 picstory — knowledge-card video
LLM writes a structured script, AI draws one card per scene, TTS narrates, FFmpeg assembles. Best for 小红书 / Twitter edu / TikTok.
Quick start
voxflow picstory --topic "AI Agent 入门指南"
voxflow picstory --topic "AI 入门" --scenes 2 --image-only
voxflow picstory --topic "How React Hooks Work" --language en --ratio landscape --style photo
Output: picstory-<timestamp>.mp4 + .json (script).
Card-type styles (structured heading + key points)
--style | Look | Best for |
|---|
sketchnote (default) | Colorful hand-drawn bullet journal | Knowledge sharing, tutorials |
neon_noir | Cyberpunk dark with neon glow | Tech, startup |
minimal_3d | Soft 3D clay on pastel gradients | 小红书 lifestyle |
chalkboard | White chalk on dark green | Science, academic |
Scene-type styles (free-form illustration)
--style | Look | Best for |
|---|
photo | Cinematic / photo-real | Storytelling, travel |
manga_panel | Japanese manga ink linework | Drama, step-by-step guides |
vintage_newspaper | 1940s broadsheet | History, factual stories |
Ratios
--ratio | Pixels | Platform |
|---|
portrait (default) | 1080×1920 | 小红书, TikTok, Reels, 抖音 |
landscape | 1920×1080 | YouTube, B站 |
square | 1080×1080 | Instagram, Twitter |
Script-model presets (--script-model)
| Preset | Provider | Strength |
|---|
| omitted | server config | Balanced default (gpt-4o-mini) |
gemini-flash | OpenRouter | Multilingual, good Chinese |
deepseek | DeepSeek | Cheapest, excellent Chinese |
hunyuan | 腾讯混元 | Chinese-native |
moonshot | Moonshot | Chinese long context |
Server enforces an allowlist — only the preset names above work; arbitrary model IDs are rejected.
Image quality (--quality)
Image generation is the only meaningful cost (~$0.005-0.08 per image). LLM script (~2K tokens) is negligible.
--quality | Provider | Strength | 5-image cost |
|---|
fast (default) | OpenRouter Gemini Flash | Cheapest, balanced | ~$0.025 |
hd | OpenRouter Gemini Pro | Higher detail | mid |
ultra | OpenRouter gpt-5.4-image-2 | Best overall, ~16× cost | ~$0.40 |
fast-aiberm | Aiberm Gemini Flash | Cheap Aiberm tier | low |
hd-aiberm | Aiberm Gemini Pro | Strongest Chinese text rendering — best for 小红书 cards with Chinese headers | mid |
Use fast for iteration; hd-aiberm when cards must contain accurate Chinese characters; ultra for hero exports.
Full options
| Flag | Default | Description |
|---|
--topic <text> | required (or --text) | Story topic |
--text <content> | — | Paste full article instead of a topic |
--style <name> | sketchnote | See styles above |
--ratio <name> | portrait | portrait | landscape | square |
--language <code> | zh | zh | en | ja | ko | ... |
--scenes <n> | 5 | 2–10. Use 2 for quick tests. |
--script-model <preset> | server default | See presets above |
--quality <tier> | fast | See table above |
--voice <id> | default | TTS voice from voxflow voices |
--speed <n> | 1.0 | TTS speed 0.5–2.0 |
--bgm <file> | — | Background music (mp3/wav) mixed under narration |
--bgm-volume <n> | 0.1 | BGM volume 0–1 |
--fade <n> | 0.4 | Per-scene fade in/out seconds (0 to disable) |
--image-only | false | Save images + audio without final video render |
--output-dir <dir> | — | Directory for all outputs |
--output <path> | auto | Final MP4 path |
Quota cost
| Operation | Quota |
|---|
| LLM script | 100 |
| TTS / scene | 50 |
| Image / scene | 500 |
| 2-scene test | ~1,200 |
| 5-scene full | ~2,850 |
Free tier (10K/month) ≈ 3 full picstory videos.
Pipeline
Topic / Text
├─[1] LLM script → { title, scenes: [{ heading, keyPoints, narration }] }
├─[2] TTS per scene → PCM audio
├─[3] Image per scene (parallel) → JPEG via /api/image/generate
└─[4] FFmpeg: image + WAV → Ken Burns zoompan MP4 → concat → +BGM → final.mp4
Troubleshooting
| Problem | Fix |
|---|
ffmpeg not found | brew install ffmpeg (mac) / sudo apt install ffmpeg |
Image generation failed | Retry; if stuck on hd, drop to --quality fast |
| Render too slow | Ken Burns is CPU-heavy. Use --scenes 2 --image-only to validate content first. |
model_not_allowed | Use a --script-model preset name, not a raw model ID |
| Chinese text mangled in cards | Switch to --quality hd-aiberm |
📑 present — narrated card video (Remotion local)
Text or URL → LLM cards → TTS → Remotion render. 1080×1920, 5 visual schemes.
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
| Flag | Default | Notes |
|---|
--text / --url / --cards | one required | input source |
--style | aurora | noir | neon | editorial | aurora | brutalist |
--voice <id> | v-female-R2s4N9qJ | TTS voice |
--speed <n> | 1.0 | 0.5–2.0 |
--no-audio | false | Silent video only |
--web-search | false | Augment LLM with up-to-date web facts |
--output <path> | ./present-<ts>.mp4 | .mp4 or .wav |
If present reports "Remotion not ready", run npm install inside the bundled remotion-cards/ directory to set up the local renderer.
🧠 explain — AI explainer video
Title / bullets / summary scene flow. Best for "What is X?" tutorials.
voxflow explain --topic "What is React?"
voxflow explain --topic demo --output demo.mp4
voxflow explain --topic "区块链入门" --style chalkboard --voice v-male-Bk7vD3xP
voxflow explain --topic "Machine Learning" --audio-only
voxflow explain --topic "AI Agent 入门" --cloud
| Flag | Default | Notes |
|---|
--topic <text> | required | Use demo for built-in demo script |
--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 | Skip render, output WAV only |
--cloud | false | Use cloud Remotion instead of local |
--output <path> | ./explain-<ts>.mp4 | |
📊 slides — HTML presentation with TTS
Generates a self-contained HTML deck with embedded base64 audio per slide. Open in any browser, no server needed.
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
| Flag | Default | Notes |
|---|
--text <text> (or positional) | required | Topic |
--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 | Skip TTS, slides only |
--output <path> | ./slides-<ts>.html | |
10 layouts: hero, title-bullets, two-column, three-cards, image-left, image-right, quote, timeline, stats, section. Templates auto-pick a layout sequence.
🖼 image — single Hunyuan illustration
Synchronous text → image (PNG). Useful for thumbnails or one-off art.
voxflow image "a sleeping cat in a sunlit window" --resolution 1024:1024 -o cat.png
Resolutions: 768:768, 768:1024, 1024:768, 1024:1024, 720:1280, 1280:720, 768:1280, 1280:768, 1080:1920, 1920:1080.
Prompt max 1000 chars. Output: local PNG + COS URL.
Pick-the-right-tool checklist
"小红书风格知识卡片" → picstory
"AI 短视频 + caption" → picstory --style sketchnote
"explainer / What is X?" → explain
"branded short with my text" → present
"already have cards/script" → present --cards
"shareable HTML deck w/ audio" → slides
"single illustration" → image
Rules
- Search voices with
voxflow voices before passing --voice. Never guess IDs.
- Check quota before video calls (
voxflow status): picstory ≈ 3K, present/explain ≈ 500–2K.
- Test cheap first:
picstory --scenes 2 --image-only validates the script before paying for full render.
- After render finishes, auto-play:
open output.mp4 (macOS).
