Builder API

Create App Store screenshots programmatically. Send natural language messages, get back canvas state JSON with device mockups, backgrounds, and text.

Authentication

All API requests require a Bearer token in the Authorization header. Create API keys in Settings → API Keys.

Authorization: Bearer sk_live_your_key_here

Base URL

https://appscreenshotstudio.com/api/v1

Endpoints

POST/projects

Create a new builder project. Optionally pass codebase_context to persist app context for all future chats.

Request body

{
  "device_id": "iphone-6.9",   // or "android-phone"
  "name": "My App Screenshots", // optional
  "codebase_context": {         // optional — persisted for all chats
    "readme_summary": "A habit tracking app...",
    "key_screens": ["Dashboard", "Settings", "Profile"],
    "color_tokens": { "primary": "#7C3AED" },
    "target_audience": "busy professionals",
    "app_category": "productivity",
    "competitive_edge": "AI-powered habit suggestions",
    "ui_style": "dark mode with purple accents",
    "primary_user_flow": "Sign up → Add habits → Track daily → View streaks"
  }
}

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "My App Screenshots",
    "device_id": "iphone-6.9",
    "canvas_state": { "cards": [], "codebaseContext": {...}, ... }
  },
  "credits_remaining": 74
}

GET/projects

List all your builder projects.

Response

{
  "success": true,
  "data": [ ... ],
  "credits_remaining": 74
}

GET/projects/:id

Get a project with its full canvas state.

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "canvas_state": { "cards": [...], ... },
    ...
  },
  "credits_remaining": 74
}

POST/projects/:id/chat

Send a message to build screenshots. Costs 5 credits per message.

Request body

{
  "message": "Create 5 App Store screenshots for a fitness app called FitPro",
  "images": [                          // optional
    { "dataUrl": "data:image/png;base64,..." }
  ],
  "selected_card_indices": [0, 1]      // optional
}

Response

{
  "success": true,
  "data": {
    "message": "Created 5 cards with ...",
    "operations": [ ... ],
    "canvas_state": { "cards": [...], ... },
    "suggestions": ["Add ratings", "Change colors", ...]
  },
  "credits_remaining": 73
}

PATCH/projects/:id

Update a project's name, device, or canvas state.

Request body

{
  "name": "Updated Name",             // optional
  "device_id": "android-phone",       // optional
  "canvas_state": { ... }             // optional
}

DELETE/projects/:id

Delete a project.

Response

{ "success": true }

POST/projects/:id/upload-screenshots

Upload app screenshots into device mockup elements. Maps each screenshot to a card by index. Free — no credit cost.

Request body

{
  "screenshots": [
    { "card_index": 0, "image_base64": "iVBORw0KGgo..." },
    { "card_index": 1, "image_base64": "data:image/png;base64,iVBOR..." }
  ]
}

Response

{
  "success": true,
  "data": {
    "uploaded": 2,
    "results": [
      { "card_index": 0, "success": true },
      { "card_index": 1, "success": true }
    ]
  },
  "credits_remaining": 74
}

POST/projects/:id/render

Render all cards as PNG images. Free — no credit cost. No request body needed.

Response

{
  "success": true,
  "data": {
    "images": [
      { "card_index": 0, "url": "https://...png", "width": 1260, "height": 2736 },
      { "card_index": 1, "url": "https://...png", "width": 1260, "height": 2736 }
    ]
  },
  "credits_remaining": 68
}

POST/projects/:id/generate-background

Generate an AI background for one card with Gemini. The image is cropped to exact device dimensions and applied to the card's background element. Costs 6 credits. Requires Growth plan or higher.

Request body

{
  "card_index": 0,
  "prompt": "Deep purple nebula with soft pink and blue light rays"
}

Response

{
  "success": true,
  "data": { "card_index": 0 },
  "credits_remaining": 62
}

Rate Limits

Rate limit info is included in response headers.

Endpoint	Limit
POST /projects/:id/chat	60 requests / 5 minutes
All other endpoints	120 requests / minute

Errors

{
  "success": false,
  "error": "Human-readable message",
  "code": "ERROR_CODE"
}

Code	HTTP	Meaning
UNAUTHORIZED	401	Invalid or revoked API key
NO_CREDITS	402	Insufficient credits
NOT_FOUND	404	Project not found or not yours
VALIDATION_ERROR	400	Invalid request body

Canvas Elements

The AI creates screenshots by composing these element types on a canvas. When you send a chat message, the AI returns operations that add, update, or remove these elements. Understanding them helps you write better prompts.

background

Every card has one. Supports solid colors, multi-color gradients with angle control, or AI-generated images via a text prompt.

bgType: "solid" | "gradient" | "image"
color — solid fill color
gradientColors — array of 2+ colors
gradientAngle — 0-360 degrees
backgroundPrompt — text description for AI background generation

Example prompt

“"Make card 1's background a dark blue to purple gradient at 135 degrees"”

text

Rich text with per-word color, weight, italic, underline, highlight pills, gradient fills, stroke outlines, and emoji support.

content — the text string
fontSize, fontFamily, fontWeight, color, alignment
segments — per-word styling: color, fontWeight, italic, underline, highlightColor
highlightColor — rounded colored pill behind a word (like pro App Store screenshots)
underline — boolean, draws underline under specific words via segments
italic — boolean, renders words in italic via segments
letterSpacing — pixel spacing between letters (-3 to 20). Negative = tight headlines, positive = elegant subtitles
textStroke — { color, width } outline around text for contrast on busy backgrounds
gradientColors + gradientAngle — gradient fill across entire text
Emoji render natively at font size (e.g. "Track Meals 🍎")

Example prompt

“"Make the headline 'Scan Any Food' with 'Any' in a blue highlight pill, 'Food' underlined"”

device-mockup

Phone or tablet frame with a screenshot slot. Supports 9 perspective variants for 3D angles and a recolorable frame finish.

deviceId — "iphone-6.9" | "ipad-13" | "android-phone" | "android-tablet-10" | "apple-watch-ultra"
frameStyle — "realistic" | "none"
frameColor — "natural" | "black" | "white" | "gold" (default "natural"; Growth plan or higher)
perspectiveVariant — "flat" | "left-15" | "left-30" | "right-15" | "right-30" | "isometric" | "top-down" | "landscape-left" | "landscape-right"
screenshotImage — uploaded via upload-screenshots endpoint or the web UI

Example prompt

“"Tilt the phone to 15 degrees left and recolor the frame to gold on card 3"”

shape

94 shape types (17 core + 77 decorative across 13 categories) for decorative elements, glow orbs, floating UI panels, laurel wings, and more.

Core shapes: rectangle | circle | rounded-rect | ellipse | blob | triangle | diamond | hexagon | ring | semicircle | cross | star | wave | path | wing-left | wing-right | line
Decorative library (78+ shapes): nature (leaf, flower, tree, palm-tree, cactus), weather (cloud, sun, moon, snowflake, lightning-bolt), celebration (sparkle, heart, trophy, crown, medal, confetti), social (chat-bubble, thumbs-up, music-note, camera, globe), tech (rocket, code-bracket, wifi, shield), health (dumbbell, flame, yoga), food (coffee-cup, cupcake, pizza), travel (airplane, compass, map-pin), finance (dollar-sign, chart-up, piggy-bank), education (graduation-cap, pencil, lightbulb), pets (paw-print, cat-face), emoji (smiley, fire-emoji, wink), abstract (swirl, infinity, gem, checkmark)
fill, stroke, strokeWidth, cornerRadius
strokeDash — [dash, gap] for dashed/dotted borders (e.g. [10, 5])
arrowStart / arrowEnd — boolean, adds arrowheads to line shapes for annotations
blurAmount — 0-20, softens/diffuses the shape (great for glow orbs)
gradientColors + gradientAngle — gradient fill
Wing shapes: wing-left + wing-right for laurel stats (e.g. flanking "4.9 Rating" or "1M+ Users")
Wave-specific: waveStartY, waveEndY, waveFillSide, waveCurve
Path-specific: pathData (SVG path in 100x100 coordinate space)

Example prompt

“"Add laurel wings around a 4.9 star rating, scatter leaf and sparkle shapes in the background"”

badge

Colored label with text — for 'App of the Day', '#1 in Health', etc.

text, bgColor, textColor, borderRadius

Example prompt

“"Add a '#1 Health App' badge below the phone"”

star-rating

5-star rating display with custom color.

rating (1-5), starColor, size

Example prompt

“"Add a 4.8 star rating in gold below the headline"”

image

General image element for 3D illustrations and decorative graphics.

src — image URL (upload via UI or AI Image generator)

Example prompt

“"Add a 3D illustration of a running shoe floating next to the phone"”

icon

App icon or small image with optional rounded corners.

src, borderRadius

Example prompt

“"Add my app icon in the top corner"”

Shared Properties

Every element supports these base properties:

x, y          — position on canvas
width, height  — size
rotation       — degrees
opacity        — 0 to 1
zIndex         — layer order (0 = back, higher = front)
shadowColor, shadowBlur, shadowOffsetX, shadowOffsetY

Supported Devices

Device ID	Name	Canvas Size
iphone-6.9	iPhone 16 Pro Max	1260 × 2736
ipad-13	iPad Pro 13"	2064 × 2752
android-phone	Android Phone	1080 × 2340
android-tablet-10	Android Tablet 7"	1200 × 1920
apple-watch-ultra	Apple Watch Ultra 2	410 × 502

Layouts & Panoramics

The chat endpoint composes each card from one of nine layout templates. You don't pass these as schema fields — describe the effect in natural language and the AI picks the layout, narrative arc, and parameters.

14 layouts

Layout	Use for
text-top-device-bottom	Headline top, flat device bottom — feature/educate cards
text-top-device-tilted	Headline left, tilted device right (or mirrored)
device-hero	Headline + large centered device — product-forward
social-proof	Stars + quote + laurel stat, no device (testimonial-led)
review-clip	Rating-statement headline + stars + quote + bottom-clipped device
screen-hero	Top-clipped device + centered headline + optional trust stat
lifestyle-hero	Full-bleed photo background + text overlay, no device
photo-device-hero	Full-bleed photo + flat device + headline overlay at top
feature-grid	Headline + 2×2 or 2×3 icon+label grid, no device
before-after	Dark before-half + bright after-half (transformation apps)
stats-hero	Giant centered stat(s), no device, numbers-led
metric-badge	Centered device + chunky "achievement card" over its screen
annotated-feature	Tilted device + side callout chip linked by a connector line
step-flow	Headline + 2-4 numbered step rows ("how it works"), no device

Layout params (set per card by the AI): deviceScale (small/medium/large), deviceSide (left/right), textPosition (above/below), textAlign (left/center).

Compound fields

Auto-positioned trust signals attached to a card. The AI places them inline based on the chosen layout.

· statRow — three side-by-side metrics (e.g. “1M+ users · 4.9 rating · 150 countries”)
· laurelStat — wing-left + wing-right shapes flanking a hero number
· starRating — five stars with optional rating value
· quote — testimonial text + attribution
· pressBanner — “Featured in TechCrunch · Wired · The Verge”-style logos row
· featureGrid — 2×2 or 3×1 feature tiles
· beforeAfterSplit — paired before/after labels for split cards

Panoramics

Stretch one image or element across multiple adjacent cards so they read as a continuous panoramic when the App Store gallery scrolls. Two flavors:

apply_panoramic — slices one wide image (AI-generated or Pexels) across the background elements of N cards. The gallery gap (per device category) is accounted for so slices line up after Apple's gutter.
apply_element_span — stretches a single foreground image, device-mockup, or shape across adjacent cards.

Panoramic background

Pano the background photo across cards 1-3 with a moody twilight gradient.

Panoramic element span

Stretch the device on card 1 across into card 2 so it reads as one continuous phone.

Frame color

Recolor the device frame across cards. Values: natural (default), black, white, gold. Requires Growth plan or higher.

Frame color

Recolor the iPhone frame to gold across all cards.

Prompt Tips

The chat endpoint understands natural language. Here are prompts that work well:

Create from scratch

Create 5 App Store screenshots for a meditation app called ZenFlow. Use calming blues and purples.

With app screenshots

Here are my app screens. Create 4 professional screenshots with headlines and a dark theme.

Attach images via the images array

Style specific cards

Make card 1 a title card with no phone — just a big headline with highlight pills and a star rating.

Refine

Make the headlines bolder, add text stroke for contrast, and use emoji in the headings.

Perspective

Tilt all phones to left-15 perspective and add floating UI snippets.

Theme change

Switch everything to a warm sunset gradient theme with coral and gold.

Laurel stats

Add laurel wings around a 4.9 star rating on the social proof card, and a 1M+ Users stat on the CTA card.

Decorative shapes

Scatter leaf and sparkle shapes in the background. Add a trophy shape near the headline.

Text styling

Make 'Every' underlined and italic, put 'Free' in a green highlight pill.

Quick Start

# 1. Create a project
curl -X POST https://appscreenshotstudio.com/api/v1/projects \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"device_id": "iphone-6.9", "name": "FitPro"}'

# 2. Build screenshots via chat (5 credits per message)
curl -X POST https://appscreenshotstudio.com/api/v1/projects/PROJECT_ID/chat \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Create 5 screenshots for a fitness app"}'

# 3. Iterate
curl -X POST .../chat \
  -d '{"message": "Make the backgrounds darker and add star ratings"}'

# 4. Render as PNGs (free)
curl -X POST https://appscreenshotstudio.com/api/v1/projects/PROJECT_ID/render \
  -H "Authorization: Bearer sk_live_your_key"

MCP Server

Using Claude Code, Cursor, or another MCP-compatible agent? Install the MCP server and your agent gets screenshot generation as a native tool — no manual API calls needed.

MCP Setup Guide →