BlitzReels Faceless Video Generation

Generate AI-powered faceless videos from a topic or script.

Cost Warning: Faceless generation consumes AI credits (AI script writing, image generation, voiceover, video assembly). You MUST present a plan to the user and get approval before calling any expensive endpoint.

Quick Start

# Full pipeline: topic → video
bash scripts/faceless.sh --topic "5 productivity tips" --duration 30 --voice rachel --style cinematic

# Dry run — show plan without executing
bash scripts/faceless.sh --topic "5 productivity tips" --dry-run

# From a user-provided script (paragraph breaks = scene breaks)
bash scripts/faceless.sh --script "First scene narration.\n\nSecond scene narration." --duration 60

Required Workflow

Always use plan mode. Before generating, present this plan to the user for approval:

1. Topic or script — What the video is about
2. Duration — 10–120 seconds (drives scene count)
3. Visual style — See references/visual-styles.md or GET /visual-styles
4. Voice — See references/voices.md or GET /voices
5. Image model — See references/models.md (default: gemini-2.5-flash)
6. Video model — See references/models.md (default: kling-2.1)
7. Output mode — Full video, storyboard-only (images), or images + audio
8. Captions — Enabled by default; optionally pick a caption style
9. Plan summary — Present all choices + "this will consume AI credits" warning
10. User approval → Execute

Input Modes

| Mode | Flag | Behavior | |------|------|----------| | Topic | --topic "..." | AI writes the script based on the topic | | Script | --script "..." | User provides exact narration. Paragraph breaks (\n\n) become scene breaks. |

If both are provided, --script takes precedence.

Scripts

scripts/faceless.sh

Purpose-built end-to-end pipeline. Handles: create project → generate → poll → export → download URL.

faceless.sh --topic TEXT [--duration 30] [--voice rachel] [--style cinematic]
            [--image-model ID] [--video-model ID] [--video-duration SEC]
            [--storyboard-only] [--no-animated-video]
            [--aspect 9:16] [--captions true] [--caption-style ID]
            [--resolution 1080p] [--name TEXT] [--yes] [--dry-run]

Run bash scripts/faceless.sh --help for full usage.

scripts/blitzreels.sh

Generic API helper for ad-hoc calls. Requires BLITZREELS_ALLOW_EXPENSIVE=1 for expensive endpoints.

bash scripts/blitzreels.sh METHOD PATH [JSON_BODY]

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | BLITZREELS_API_KEY | Yes | API key for authentication | | BLITZREELS_API_BASE_URL | No | Override base URL (default: https://www.blitzreels.com/api/v1) | | BLITZREELS_ALLOW_EXPENSIVE | No | Set to 1 to allow expensive calls via blitzreels.sh |

API Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /projects | Create a new project | | POST | /projects/{id}/faceless | Start faceless generation (expensive) | | GET | /jobs/{job_id} | Poll job status | | GET | /projects/{id}/context?mode=timeline | Inspect generated timeline | | POST | /projects/{id}/export | Start export (expensive) | | GET | /exports/{export_id} | Get export status + download URL | | GET | /voices | List available voices | | GET | /visual-styles | List available visual styles | | GET | /caption-styles | List caption style presets |

Faceless Request Body

{
  "topic": "5 morning routine tips",
  "duration_seconds": 30,
  "visual_style": "cinematic",
  "voice_id": "21m00Tcm4TlvDq8ikWAM",
  "captions": true,
  "caption_style": "bold-center"
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | topic | string | one of topic/script | AI generates script from this | | script | string | one of topic/script | Exact narration text, paragraph breaks = scenes | | duration_seconds | number | yes | 10–120 | | visual_style | string | no | Style ID (default: cinematic) | | voice_id | string | no | ElevenLabs voice ID (default: Rachel) | | captions | boolean | no | Enable captions (default: true) | | caption_style | string | no | Caption style preset | | imageModelId | string | no | Image generation model (default: google-gemini-2.5-flash-image) | | videoModel | string | no | Video generation model (default: kling-2.1) | | videoDuration | number | no | Per-clip duration in seconds, 3–10 | | storyboardOnly | boolean | no | Generate images only, skip video/audio (default: false) | | generateAnimatedVideos | boolean | no | Set false to skip video animation (default: true) |

Generation Modes

| Mode | Flag | What's Generated | |------|------|-----------------| | Full video (default) | — | Images → video clips → voiceover → music → captions | | Storyboard only | --storyboard-only | Scene images only (no video, no audio). Cheapest option for previewing. | | Images + audio | --no-animated-video | Scene images + voiceover + music (slideshow-style, no video animation) |

References

• references/models.md — All image and video generation models with costs and capabilities
• references/voices.md — All available voice IDs, categories, and descriptions
• references/visual-styles.md — All available visual style IDs and descriptions

Safety

• faceless.sh prompts for confirmation before calling expensive endpoints (bypass with --yes)
• blitzreels.sh requires BLITZREELS_ALLOW_EXPENSIVE=1 for /faceless and /export paths
• Always present cost/plan to user before generation

Notes

• Use https://www.blitzreels.com/api/v1 as your base URL. https://blitzreels.com redirects to www, and some HTTP clients drop the Authorization header on redirects.
• POST /projects/{id}/faceless returns a plan and input_warnings to help you predict what will be generated.
• Full OpenAPI spec: https://www.blitzreels.com/api/openapi.json

Rate Limits

| Plan | Requests/min | |------|-------------| | Free | 10 | | Creator | 30 | | Pro | 60 | | Agency | 120 |