How Pitchstage works

1. The mental model

project  →  outline  →  scenes  →  artifacts

• Project — your launch: the product input (URL or screenshots) + a goal.
• Outline — the director’s draft script: a hook, beats, and a call-to-action. Fully editable — it’s the single source the artifacts render from.
• Scenes — each screenshot becomes a scene with narration + a camera move.
• Artifacts — what ships: a demo video (16:9 / 9:16 / 1:1), a carousel, and copy.

Everything downstream comes from the outline, so editing the outline (or a scene) re-shapes the video and carousel together.

2. Make your first launch (in the app)

No install, no API key. Roughly two minutes of input, then a render.

1. New project → pick a launch type. Feature drop, major release, funding milestone, Product Hunt launch, changelog, or custom — this sets the narrative shape.
2. Add your product. Paste your app URL and the director drives it like a person and captures each screen, or drop 3–20 screenshots (PNG/JPG/HEIC, ≤10 MB each). Behind a login? See “behind a login” below.
3. Describe what you shipped — one paragraph. This steers the outline; you can edit or re-draft it.
4. Review the outline. The director drafts the hook, the beats (one per feature), and the CTA. Edit any line — this is your script.
5. Brand + voice (optional). A brand kit (colors, font) and a voice profile (paste a few of your posts; it learns your tone) make the output look and sound like you. There’s always a sensible default, so you can skip this.
6. Pick your artifacts and per-artifact options (aspect ratio, captions, music, hook and CTA cards, smart-zoom, transitions).
7. Refine scenes (optional). Per scene you can tune narration, duration, importance, the camera move, an on-screen pull-quote, and the layout.
8. Render. Watch progress live (~30–90s for a real flow); download the video, carousel, and copy when it’s done.

3. What the director can do

The director isn’t a template filler — it makes editorial decisions and reconciles incoherent input (and tells you what it changed). Its toolkit:

Narrative templates

feature_drop · major_release · funding_milestone · product_hunt_launch · changelog · custom — each sets a different pace, opening, and CTA.

Adaptive openings

The director picks how to open for your audience: end_state_first (lead with the outcome), cold_open_problem (lead with the pain), straight_to_product (jump in — good for developer audiences), or brief_intro.

Motion (per scene)

And

• Hero emphasis — your one differentiating feature gets extra screen-time, words, and motion.
• Smart zoom — pushes into the key element as the narration reaches it.
• Transitions — hard cuts or crossfades.
• Kinetic text — a ≤6-word pull-quote on screen, separate from the spoken narration.
• Portrait layout (9:16) — a phone-frame split or a blurred backdrop.
• Music — none, a library track, or your own upload, auto-ducked under narration.
• Captions — karaoke (word-by-word), plain, sparse, or off.
• Your voice + brand — narration and copy in your tone; your colors and font on every frame.

4. What you can configure (the plan)

Every render is described by one resolved plan. It’s tiered: stick to intent for the 80% case; reach into director and scenes for fine control. The app edits these for you; agents send them as JSON.

Tier 1 — intent (the 80%)

Tier 2 — director (stable)

Tier 3 — scenes (advanced, no stability promise)

Per-scene overrides: durationS, narrationText, emotion, importance, kineticText, emphasisPhrase, motionPlan, layout (full_bleed / device_frame / split / collage / slide), and more.

The director reconciles — it never silently obeys

Send something incoherent and it fixes it, returning a warnings[] note so you know:

5. Drive it with agents, the CLI, or the API

The same engine is fully headless — point an AI agent, a terminal, or CI at it. It’s a two-phase loop: a cheap plan (resolved config + preview frames + a fit-score, no render cost) that you iterate on, then one billable render.

First: mint an API key

In the app go to Settings → API keys → Create key. Choose scopes — plan (read-only, free) and/or render (billable) — and a monthly spend cap. The raw key pk_live_… is shown once. Defaults per key: 60 requests/min and a $5/mo spend cap.

A. From an AI agent (MCP — Claude, Cursor)

1. Mint a render-scope key (above).
2. Add the Pitchstage MCP server to your client config and paste your key:

{
  "mcpServers": {
    "pitchstage": {
      "command": "npx",
      "args": ["-y", "@pitchstage/mcp"],
      "env": { "PITCHSTAGE_API_KEY": "pk_live_…" }
    }
  }
}

Restart the client. The agent now has five tools:

A natural agent loop: create_project → upload screenshots → plan → look at the preview frames + fit-score, tweak the plan, plan again → render → get_render. Because plan returns the frames as images, the agent can judge and improve the result before spending a render. (Optional base URL override: PITCHSTAGE_API_URL, default https://pitchstage.ai/api.)

B. From the terminal / CI (CLI)

npm i -g pitchstage          # or: pnpm add -g pitchstage
export PITCHSTAGE_API_KEY=pk_live_…

Point it at a folder of screenshots. Each subfolder is a feature (one outline beat); loose images become an “Overview”:

screenshots/
  Inbox/      a.png  b.png    →  feature "Inbox"
  Settings/   c.jpg           →  feature "Settings"
  cover.png                   →  "Overview"

pitchstage render ./screenshots --goal "30s launch teaser for developers"

C. Straight HTTP (the API)

Prefer raw requests? Every endpoint, the resolved-plan contract, error codes, and limits are in the headless API reference (the machine-readable spec is at /api/v1/openapi.json).

Q&A