# PromoShots — agent guide PromoShots turns app screenshots into polished App Store screenshot sets. As an agent you describe a set with a small JSON "spec"; PromoShots compiles it into a real project and renders pixel-exact PNGs at Apple's required sizes. ## The PromoSpec ```jsonc { "name": "My App", // optional, shown in the editor "preset": "iphone-6.9", // export size + default device (see Presets) "font": "sora", // optional heading font id (see Fonts) "unifiedBackground": false, // true = one gradient spans all screens "set": "panorama", // optional: multi-screen set preset (see Sets) — // expands to a full 5–10 screen row; `screens` // then just overrides by index (copy, screenshots) "screens": [ // 1..10 screens; each = one screenshot { "template": "aurora", // sets layout + background + accent (see Templates) "headline": "Your money, finally smart.", "subhead": "AI insights on every dollar", "screenshot": "https://.../home.png", // http(s) or data: URL of the app screen "screenshot2": "https://.../detail.png", // optional: back device on `device-duo` "layout": "caption-top", // optional: override just the layout "background": "deep-ocean", // optional: a background id OR raw CSS "device": "iphone-16-pro", // optional: device frame override "finish": "natural", // optional: device finish id "accent": "#21D4FD", // optional: accent color "deviceScale": 1, // optional 0.5–2.5: enlarge the device to fill the frame "rotation": 0, // optional -45–45: clockwise device tilt (degrees) "deviceOffsetX": 0, // optional -1–1: nudge device X (fraction of frame width) "deviceOffsetY": 0 // optional -1–1: nudge device Y (fraction of frame height) } ] } ``` Provide `screens` (each screen works with no fields at all — it falls back to the default template) or a `set` id — everything else is optional with sensible defaults. Unknown template / font / background / finish ids degrade gracefully to defaults; unknown preset / device ids are hard errors. A `set` is a complete, art-directed 5–10 screen story: alternating caption positions, dual-device frames, optionally one gradient across the whole row and "bridge" devices that straddle the seam between two screenshots so the gallery reads as one continuous scene. With `set`, pass `screens` as sparse per-index overrides — e.g. `{"set":"panorama","screens":[{"headline":"...","screenshot":"..."},{}]}` keeps the set's design but swaps your copy/screenshots in. `deviceScale` / `rotation` (with `deviceOffsetX`/`deviceOffsetY`) are modifiers on any framed layout — `deviceScale` > 1 enlarges the device to fill or bleed past the frame (the direct fix for dead space on `caption-over` / `caption-top`); `rotation` tilts it for an angled hero. Out-of-range values are clamped, not rejected, and `full-bleed` ignores them. ## Auth Discovery is public: `GET /llms.txt`, `GET /api/catalog`, `POST /api/compile`. Rendering is gated — `POST /api/render` and **all** MCP calls require a PromoShots API key. Create one in the app (account menu → "API keys") and send it as `Authorization: Bearer psk_...`. For the remote MCP, configure it as the server's bearer token. Each user is rate-limited on renders. ## How to use it 1. GET https://www.promoshots.app/api/catalog — the live list of valid ids (or call the MCP tool `list_catalog`). 2. Build a PromoSpec. Aim for short, punchy headlines (2–5 words) and a single supporting subhead per screen. 3–5 screens is typical. 3. Either: - POST https://www.promoshots.app/api/render { spec } — get finished PNG URLs back, or - call the MCP tool `create_screenshots` — renders + returns an "open in editor" link so a human can tweak before exporting, or - POST https://www.promoshots.app/api/compile { spec } — get the internal project JSON (no render). ## Presets (export sizes) - iphone-6.9: iPhone 6.9" 1290x2796 (Apple-required) - iphone-6.5: iPhone 6.5" 1242x2688 - iphone-5.5: iPhone 5.5" 1242x2208 - ipad-13: iPad 13" 2048x2732 (Apple-required) - ipad-11: iPad 11" 1668x2388 Apple requires a 6.9" iPhone set and a 13" iPad set; smaller sizes are optional. Up to 10 screenshots per size. ## Sets (full multi-screen presets) - story-arc: Story Arc — 6 screens · hook → features → proof → CTA, alternating captions (6 screens) - panorama: Panorama — 5 screens · one gradient, devices spanning across screenshots (5 screens, unified background, 2 seam-spanning devices) - double-take: Double Take — 5 screens · dual-screenshot frames and split layouts (5 screens) - clean-sweep: Clean Sweep — 8 screens · calm corporate set, alternating captions (8 screens) - neon-arc: Neon Arc — 10 screens · max-energy full set with a spanning centerpiece (10 screens, unified background, 1 seam-spanning device) - zen-flow: Zen Flow — 5 screens · serene meditation-app arc, one soft gradient (5 screens, unified background, 1 seam-spanning device) - money-talks: Money Talks — 6 screens · fintech trust arc — clarity, control, proof (6 screens) - glow-up: Glow Up — 6 screens · AI photo-editor arc, full-bleed results up front (6 screens, unified background) - first-match: First Match — 5 screens · warm dating-app arc ending on a bright CTA (5 screens) ## Templates - aurora (centered-hero, bg electric-grape) e.g. "Your money, finally smart." - linen (centered-hero, bg paper) e.g. "Write like it's paper." - midnight-pro (split-device-left, bg deep-ocean) e.g. "Ship faster. Sleep better." - sherbet (caption-top, bg peach-sorbet) e.g. "Plan your day in 10 seconds." - halo (minimal-solid, bg cotton-sky) e.g. "breathe." - voltage (full-bleed, bg vapor) e.g. "Game on." - ledger (caption-top, bg emerald-finance) e.g. "Every cent accounted for." - atelier (split-device-right, bg bone) e.g. "Design without the chrome." - solar (caption-over, bg golden-hour) e.g. "Wake up to better mornings." - frost (centered-hero, bg slate-pro) e.g. "All your work, one window." - bloom (caption-top, bg bubblegum) e.g. "Loved by 2M+ creators." - eclipse (centered-hero, bg obsidian-glow) e.g. "Focus mode, perfected." - pulse (tilted-hero, bg sunset-laser) e.g. "Crush every workout." - duet (device-duo, bg cotton-sky) e.g. "Better together." - skyline (caption-bottom, bg deep-ocean) e.g. "Your portfolio, live." - noir (split-device-right, bg graphite) e.g. "Quiet luxury, on demand." - tide (caption-bottom, bg trust-blue) e.g. "Every step counts." - orbit (device-duo, bg cyber-mint) e.g. "Two taps to production." - meadow (caption-over, bg mint-cream) e.g. "Eat greener this week." - ember (tilted-hero, bg coral-dusk) e.g. "Meet your people." - lumen (centered-hero, bg aurora-veil) e.g. "Sleep deeper tonight." - forge (tilted-hero, bg molten) e.g. "Train like you mean it." - nova (caption-bottom, bg ultraviolet) e.g. "AI edits in one tap." - seaside (device-duo, bg sea-glass) e.g. "Plan trips together." - zest (caption-top, bg citrus-pop) e.g. "Snack smarter." - regal (split-device-left, bg royal-dusk) e.g. "One source of truth." - afterdark (caption-over, bg midnight-bloom) e.g. "Nights made social." ## Layouts - caption-top: Headline + subhead at the top, device bleeds off the bottom. The workhorse. - caption-bottom: Mirror of caption-top: device bleeds off the top, caption at the bottom. Alternate the two across a set. - caption-over: Device bleeds, caption overlaps near the top. - centered-hero: Fully visible device, calm and centered. - split-device-left: Device bleeds off the left edge, text column on the right. - split-device-right: Device bleeds off the right edge, text column on the left. - minimal-solid: Device centered, optional single caption, no headline. - full-bleed: Edge-to-edge app screen with a floating headline pill. - tilted-hero: Oversized device tilted ~8°, bleeding bottom-right, left-aligned caption. High-energy first screen. - device-duo: Two staggered, counter-tilted devices under a centered caption. `screenshot` fills the front, `screenshot2` the back. - caption-only: Headline + subhead only, no device — for panels visually filled by a set's seam-spanning bridge device. ## Backgrounds (ids) apricot-haze, coral-dusk, golden-hour, peach-sorbet, citrus-pop, molten, paper, bone, graphite, fog, cotton-sky, lavender-milk, mint-cream, bubblegum, aurora-veil, sea-glass, electric-grape, cyber-mint, sunset-laser, ultraviolet, vapor, deep-ocean, trust-blue, slate-pro, emerald-finance, royal-dusk, obsidian-glow, midnight-bloom ## Devices (frames) + finishes - iphone-16-pro (iPhone 16 Pro): finishes natural, black, white, desert - iphone-16 (iPhone 16): finishes black, blue, pink, teal, white - iphone-se (iPhone SE): finishes black, white, red - ipad-pro (iPad Pro): finishes space-black, silver - frameless (Frameless): finishes none ## Fonts (ids) geist, inter, jakarta, manrope, dm-sans, outfit, archivo, sora, space-grotesk, bricolage, fraunces, instrument-serif ## Endpoints GET https://www.promoshots.app/api/catalog building blocks (JSON) [public] GET https://www.promoshots.app/llms.txt this document [public] POST https://www.promoshots.app/api/compile { spec } -> project JSON [public] POST https://www.promoshots.app/api/render { spec } -> { images: [url...] } [Bearer key + rate limited] MCP https://www.promoshots.app/api/mcp Streamable HTTP MCP [Bearer key] tools: list_catalog, get_instructions, validate_spec, create_screenshots Notes - screenshot images must be reachable (http(s)) or inlined as data: URLs. - Color values are CSS colors. Backgrounds can be a catalog id or raw CSS.