pixcli

Creative toolkit for AI agents. Generate images, videos, voiceover, music, and sound effects — then assemble polished output via Remotion.

Philosophy: The CLI handles complexity (task classification, prompt enrichment, model selection). You just describe what you want.

Setup

1. Install the CLI

npm install -g pixcli

Or use without installing:

npx pixcli image "a red fox in a forest"

2. Authenticate

export PIXCLI_API_KEY="px_live_..."

Get your API key at https://pixcli.shellbot.sh. The key covers all capabilities: images, video, voice, music, and sound effects.

3. Verify

pixcli --version
pixcli image "test: a simple blue circle on white background" -o test.png

Commands

pixcli image <prompt> — Generate images

pixcli image "Studio product shot of wireless earbuds, soft lighting, white background"

Models: flux-pro, flux-dev, seedream-v5, nano-banana-pro, nano-banana-2, imagen-4, imagen-4-fast, gpt-image-1

pixcli edit <prompt> — Edit images

pixcli edit "Remove the background" -i product.jpg -o product-nobg.png

Models: seedream-v5-edit, phota-enhance, rembg, recraft-upscale, aura-sr

pixcli video <prompt> — Generate video

# Image-to-video (recommended: generate still first, then animate)
pixcli video "Slow camera orbit around the product" --from product.png -o reveal.mp4

# Text-to-video (generates image automatically, then animates)
pixcli video "A cat walking through a garden at sunset" -o cat.mp4

# Extend an existing video
pixcli video "The cat jumps over a fence" --from cat.mp4 --extend -o cat-extended.mp4

Models: kling-v3-pro-i2v (cinematic, best quality), veo3-i2v (Google, native audio), wan-v2-i2v (cheap, good motion), minimax-i2v (fast), ltx-t2v (text-to-video, cheap), veo3-t2v (text-to-video, premium), grok-extend-video (extend), pixverse-v6-i2v (I2V with audio, multi-clip, styles, $0.075/sec), pixverse-v6-t2v (T2V with audio, multi-clip, styles), pixverse-v6-transition (start-to-end frame transition), pixverse-v6-extend (video extension with audio)

Opinionated approach: Always generate a still first with pixcli image, review it, then animate with pixcli video --from. This gives you control over the starting frame.

pixcli voice <text> — Text-to-speech

pixcli voice "Welcome to the future of productivity." -o voiceover.mp3
pixcli voice "Bienvenidos al futuro." --voice Sarah --language spa -o vo-spanish.mp3

pixcli music <prompt> — Generate music

pixcli music "Subtle ambient electronic, minimal beats, corporate technology feel" -d 45 -o bg-music.mp3

pixcli sfx <prompt> — Generate sound effects

pixcli sfx "Smooth cinematic whoosh transition" -d 1.5 -o whoosh.mp3
pixcli sfx "Soft digital click, subtle UI interaction" -d 0.5 -o click.mp3

pixcli job <id> — Check job status and download results

# Check status of a job
pixcli job abc123

# Wait for completion and download
pixcli job abc123 --wait -o output.mp4

Use case: Recover timed-out jobs. Video generation can take 5-8 minutes — if the CLI times out, it prints the job ID and a recovery command. Run pixcli job <id> --wait to pick up where you left off.

Global options

Read references/command-reference.md for the full parameter reference.

Opinionated creative workflow

The full production pipeline

1. Generate scene stills with pixcli image — use -n 4 for variations, pick the best. Use --search for real-world accuracy (correct logos, current brands). Use --from with multiple images to blend references
2. Edit heroes with pixcli edit — upscale, remove backgrounds, enhance
3. Animate 2-3 hero stills with pixcli video --from — cinematic motion for key moments
4. Generate voiceover with pixcli voice — one file per scene
5. Generate background music with pixcli music — one track for the full composition
6. Generate sound effects with pixcli sfx — transition whooshes, UI sounds (use sparingly)
7. Assemble everything in Remotion — timing, text, transitions, branding, audio mix
8. Render final video with npx remotion render

When to use AI video vs Remotion

Use pixcli video for:

• Hero moments: product reveals, cinematic openings, emotional beats (3-8s clips)
• Organic motion that's hard to code: water, fire, fabric, hair, camera orbits
• Image-to-video: animate a still into a living scene
• Transition inserts: short clips between Remotion scenes

Use Remotion for:

• Text animations, captions, kinetic typography
• Precise timing synced to voiceover
• Brand overlays, logos, consistent color grading
• Data visualizations, metric counters, charts
• Scene transitions (cuts, wipes, dissolves — deterministic)
• Final assembly: compositing AI video clips + stills + audio + text

The ideal combined workflow:

1. Generate scene stills with pixcli image (consistency via shared style prompts)
2. Animate 2-3 hero stills with pixcli video --from (cinematic motion)
3. Generate voiceover + music + SFX
4. Assemble everything in Remotion (timing, text, transitions, audio mix)

Audio layering strategy

• Voiceover at volume 1.0 — clear, intelligible, primary channel
• Music at 0.15-0.25 — duck under voiceover, never compete
• SFX sparse and purposeful — only when they reinforce movement
• Avoid dense music during problem framing

Quality tiers

• draft — Fast iteration, concepting, throwaway tests
• standard — Good for most production work (default)
• high — Hero shots, final delivery assets

ffmpeg local editing

Use ffmpeg for quick video/audio edits without a full Remotion project. These run locally — no API calls needed.

Video operations

# Trim video (extract 5 seconds starting at 2s)
ffmpeg -i input.mp4 -ss 00:00:02 -to 00:00:07 -c copy trimmed.mp4

# Split video at a timestamp
ffmpeg -i input.mp4 -t 5 -c copy first-half.mp4
ffmpeg -i input.mp4 -ss 5 -c copy second-half.mp4

# Merge videos (create filelist.txt first)
echo "file 'clip1.mp4'" > filelist.txt
echo "file 'clip2.mp4'" >> filelist.txt
ffmpeg -f concat -safe 0 -i filelist.txt -c copy merged.mp4

# Scale video to 1080p
ffmpeg -i input.mp4 -vf "scale=1920:1080" -c:a copy scaled.mp4

Audio operations

# Add audio track to video
ffmpeg -i video.mp4 -i music.mp3 -c:v copy -c:a aac -shortest output.mp4

# Replace audio track
ffmpeg -i video.mp4 -i new-audio.mp3 -c:v copy -c:a aac -map 0:v -map 1:a output.mp4

# Mix voiceover + music (music ducked to 20%)
ffmpeg -i voiceover.mp3 -i music.mp3 -filter_complex "[1:a]volume=0.2[music];[0:a][music]amix=inputs=2:duration=longest" mixed.mp3

# Extract audio from video
ffmpeg -i video.mp4 -vn -acodec copy audio.aac

# Get media info
ffprobe -v quiet -print_format json -show_streams input.mp4

Remotion video production

Remotion is the source of truth for timing, layout, animation, and render. Use pixcli to generate the visual and audio assets, then assemble everything in Remotion.

Bootstrapping a Remotion project

cp -r assets/templates/cinematic-product-16x9 ./my-video
cd ./my-video && npm install
npx remotion studio     # Preview
npx remotion render src/index.ts MainComposition out/video.mp4  # Render

Templates

Integrating AI video clips in Remotion

Use OffthreadVideo for AI-generated clips inside Remotion compositions:

import { OffthreadVideo, Sequence, Audio, Img, staticFile } from "remotion";

// AI video clip as a hero moment
<Sequence from={0} durationInFrames={150}>
  <OffthreadVideo src={staticFile("assets/hero-reveal.mp4")} />
</Sequence>

// AI-generated still as background
<Sequence from={150} durationInFrames={120}>
  <Img src={staticFile("assets/scene-solution.png")} style={{ width: "100%", height: "100%" }} />
</Sequence>

// Voiceover + music
<Audio src={staticFile("audio/voiceover.mp3")} volume={1} />
<Audio src={staticFile("audio/music.mp3")} volume={0.2} />

Remotion principles

• Keep all Remotion packages on the same pinned version
• Transitions: 8-18 frames, purposeful (not decorative)
• Load fonts explicitly with @remotion/google-fonts
• Always run npm run verify before npm run render
• Load reference rules from references/remotion-rules/ as needed

Read references/remotion-playbook.md for detailed Remotion implementation guidance.

Output convention

• pixcli downloads generated files to the current directory (or path specified with -o)
• Use --json for machine-readable output (pipe to jq or parse in scripts)
• All operations are synchronous from the CLI perspective (the CLI handles async polling internally)
• Video jobs may take 1-8 minutes (the CLI shows progress). If a job times out, use pixcli job <id> --wait to recover

References

Creative guidance

• references/command-reference.md — Full parameter docs for all pixcli commands
• references/creative-guidelines.md — Quality standards for productions
• references/prompt-cookbook.md — Proven prompt patterns for every task
• references/workflow-recipes.md — End-to-end recipe examples
• references/ancillary-assets.md — Asset generation strategy for Remotion scenes

Remotion

• references/remotion-playbook.md — Remotion implementation guide
• references/template-showcase.md — Template selector guide
• references/remotion-rules-index.md — Index of 30+ Remotion rule files
• references/remotion-rules/ — Detailed rules (animations, audio, text, transitions, etc.)

Templates

• assets/templates/aida-classic-16x9/
• assets/templates/cinematic-product-16x9/
• assets/templates/saas-metrics-16x9/
• assets/templates/mobile-ugc-9x16/
• assets/templates/blank-16x9/
• assets/templates/explainer-16x9/