ai-content-pipeline

name	ai-content-pipeline
description	Generate AI content (images, videos, audio, avatars) and analyze videos with AICP in QCut. Primary mode uses QCut's bundled AICP binary with secure API key injection.

AI Content Pipeline Skill

Generate AI content (images, videos, audio) and analyze media using AICP.

Reference files:

• REFERENCE.md - model specs, API endpoints, troubleshooting
• EXAMPLES.md - YAML pipeline examples

FAL API Key Setup

QCut resolves the FAL key from a 3-tier fallback (highest priority wins):

Tier	Source	How to set
1	Environment variable	export FAL_KEY=your_key
2	QCut Electron store	Editor -> Settings -> API Keys
3	AICP CLI credential store	aicp set-key FAL_KEY

Recommended for Claude Code / CLI workflows:

# Set FAL key persistently (secure hidden prompt, stored at ~/.config/video-ai-studio/credentials.env)
aicp set-key FAL_KEY

# Verify the key is stored
aicp check-keys

# Or use the bundled binary directly
./electron/resources/bin/aicp/darwin-arm64/aicp set-key FAL_KEY

Once set via any tier, QCut automatically injects the key when spawning AICP for generation commands. No .env file or GUI interaction is required.

Quick check — verify FAL key is available before generating:

aicp check-keys

If FAL_KEY shows not set, set it using any method above.

Usage Modes

Mode 1 (Recommended): QCut Bundled AICP

Use this when working inside QCut.

What QCut handles for you:

• bundled aicp binary (no local Python or pip required)
• 3-tier API key resolution (env > Electron store > AICP CLI store)
• FAL_KEY injection at spawn time for generation commands
• output path recovery and optional media auto-import in app flow

Setup steps:

1. Set your FAL key via CLI (aicp set-key FAL_KEY) or GUI (Editor -> Settings -> API Keys).
2. Use AI generation features from the app or CLI.

Notes:

• No .env file is required for normal QCut usage.
• If key is missing, app should fail fast with actionable guidance.
• Settings UI shows a source badge (env/app/cli) next to each key.

Mode 2: Standalone CLI (Debug/Dev)

Use this for local debugging outside QCut.

# Use bundled binary directly
./electron/resources/bin/aicp/darwin-arm64/aicp --version
./electron/resources/bin/aicp/darwin-arm64/aicp --help

Set keys via the CLI credential store (persistent, secure):

aicp set-key FAL_KEY
# optional
aicp set-key GEMINI_API_KEY
aicp set-key ELEVENLABS_API_KEY

Or export keys manually per session:

export FAL_KEY=your_fal_key

Mode 3: QCut CLI Key Management

QCut's Electron binary can also delegate key management headlessly:

./QCut set-key FAL_KEY      # Delegates to bundled aicp set-key
./QCut check-keys           # Shows all key statuses
./QCut delete-key FAL_KEY   # Removes a stored key

Quick Commands

Always inspect available models first in your current environment:

aicp list-models

Then use a model returned by your local list-models output.

Generate Image

aicp generate-image \
  --text "A cinematic portrait at golden hour" \
  --model MODEL_FROM_LIST_MODELS

Generate Video

aicp create-video --text "A serene mountain lake at sunset" --model wan_2_6

Generate Avatar (Lipsync)

aicp generate-avatar \
  --image-url "https://..." \
  --audio-url "https://..." \
  --model omnihuman_v1_5

Generate Voiceover

Use ByteDance Seed Audio for narration intended for a finished video:

bun run pipeline gen tts \
  -m seed_audio \
  -t "(用自然、自信、克制的产品宣传片语气，节奏明快，避免播音腔)<旁白正文>" \
  --audio-format mp3 \
  --sample-rate 48000 \
  --multilingual \
  -o media/generated/audio

Write the parenthesized performance direction in the same language as the copy. Prefer one request for one continuous narrator track so the speaker stays consistent. For split cues, pin the voice with --audio-url and reference it as @Audio1 in subsequent prompts.

Do not use operating-system TTS for final narration. It is acceptable only as a disposable timing placeholder. If Seed Audio cannot run, report the failure instead of silently shipping the placeholder.

Transfer Motion

aicp transfer-motion -i person.jpg -v dance.mp4

Analyze Video (CLI)

aicp analyze-video -i video.mp4
aicp analyze-video -i video.mp4 -t timeline -m gemini-2.5-flash
aicp analyze-video -i video.mp4 -t transcribe
aicp analyze-video -i video.mp4 -t describe -f json

Analyze Video (HTTP API)

QCut exposes video analysis through the Claude HTTP server (port 8765). Accepts video from timeline elements, media panel items, or file paths.

# Analyze from file path
curl -X POST http://localhost:8765/api/claude/analyze/PROJECT_ID \
  -H "Content-Type: application/json" \
  -d '{"source":{"type":"path","filePath":"/path/to/video.mp4"},"analysisType":"timeline","model":"gemini-2.5-flash"}'

# Analyze from media panel
curl -X POST http://localhost:8765/api/claude/analyze/PROJECT_ID \
  -H "Content-Type: application/json" \
  -d '{"source":{"type":"media","mediaId":"MEDIA_ID"},"analysisType":"timeline"}'

# Analyze from timeline element
curl -X POST http://localhost:8765/api/claude/analyze/PROJECT_ID \
  -H "Content-Type: application/json" \
  -d '{"source":{"type":"timeline","elementId":"ELEMENT_ID"},"analysisType":"transcribe"}'

# List available analysis models
curl http://localhost:8765/api/claude/analyze/models

Run YAML Pipeline

PIPELINE_PARALLEL_ENABLED=true aicp run-chain --config pipeline.yaml

Model and Feature Availability

Do not assume all documented models are enabled in every runtime.

Availability depends on:

• packaged binary build contents
• provider modules present in runtime
• API keys and account/provider access

Practical rule:

• treat aicp list-models as source of truth for your current machine/runtime

Known CLI Caveats

• list-models may emit provider initialization warnings in standalone mode.
• list-models does not reliably support --json in current upstream behavior.
• generate-image can fail if selected model is not actually available in your runtime.

Output Structure

Generated content should follow QCut project structure:

media/generated/
├── images/
├── videos/
└── audio/

This aligns with native-cli project-organization commands (init-project, organize-project, structure-info).

FAL API Direct Access

For direct API calls (not via CLI), model keys still map to endpoint slugs. See REFERENCE.md for endpoint mappings.

Key Files Reference

Component	File
Key storage & fallback	electron/api-key-handler.ts
AICP spawn + key injection	electron/ai-pipeline-handler.ts
Binary manager	electron/binary-manager.ts
Settings UI (key source badges)	apps/web/src/components/editor/properties-panel/settings-view.tsx
CLI key delegation	electron/main.ts (CLI_KEY_COMMANDS block)
Binary manifest	resources/bin/manifest.json
Video analysis handler	electron/claude/claude-analyze-handler.ts
Analysis types & API	electron/types/claude-api.ts (AnalyzeSource, AnalyzeOptions, AnalyzeResult)
Analysis HTTP routes	electron/claude/claude-http-server.ts
Analysis tests	electron/__tests__/claude-analyze-handler.test.ts
Fallback tests	electron/__tests__/api-key-aicp-fallback.test.ts