API & MCP

Generate Apple-grade 2D/3D mockups and animated MP4 clips from agents, CI, or your app. Authenticate with a dashboard API key, then call REST or the MCP JSON-RPC transport.

Authentication

Send your secret as Authorization: Bearer se_live_…. The full secret is shown once when the key is created.

POST /api/v1/generate

REST endpoint for 2D SVG/PNG, 3D WebGL stills, and MP4/GIF/WebM video. Pass templateId for Magic Template defaults; any explicit field overrides the template.

{
  "templateId": "product_hunt_hero",
  "imageUrl": "https://example.com/desktop-screenshot.png",
  "secondaryImageUrl": "https://example.com/mobile-screenshot.png",
  "motionPreset": "hero_tilt",
  "format": "mp4",
  "badgeText": "🚀 Live on Product Hunt"
}

Parameter	Type	Required	Notes
imageUrl	string	Yes	Public screenshot URL (hydrated server-side; SSRF-protected).
secondaryImageUrl	string	No	Mobile/secondary screenshot for multi-device layouts.
templateId	string	No	Magic Template id (e.g. product_hunt_hero, saas_ecosystem_dark). Explicit fields override template defaults.
mode	"2d" \| "3d"	No	Default "2d". Video formats require "3d".
layoutPreset	enum	No	single \| desktop_and_phone \| dual_iphone_cascade \| ecosystem_hero
motionPreset	enum	No	static \| hero_tilt \| 3d_float_loop \| isometric_orbit \| pan_and_zoom
format	enum	No	png \| mp4 \| gif \| webm (default "png")
durationSeconds	number	No	Clip length 1–10 (default 3). Used for video exports.
fps	15 \| 30 \| 60	No	Video frame rate (default 30).
badgeText	string	No	Callout overlay text (max 80 chars).
hardwareModel	string	No	e.g. macbook_pro_16, iphone_16_pro, floating_glass_pane
cameraAngle	string	No	3D camera preset (isometric_left, hero_tilt, …)
lightingPreset	string	No	3D lighting mood (studio_soft, cyber_neon, …)
backgroundPreset	string	No	2D theme or 3D stage background preset

POST /api/mcp

JSON-RPC 2.0 MCP transport for Cursor, Claude Desktop, and custom agents.

Supported methods: initialize, tools/list, tools/call, ping.

generate_marketing_shot

Primary generation tool. Produces 2D SVG/PNG, 3D WebGL stills, and animated MP4/GIF/WebM. Accepts the same fields as the REST body, including templateId, layoutPreset, motionPreset, and format.

list_magic_templates

Returns 12+ curated presets with semantic aiGuidance (bestFor, platforms, vibe, recommended aspect). Optional category filter.

list_studio_capabilities

Discovers server-supported modes (2d/3d), hardware models, lighting, cameras, layouts, motion presets, output formats, and compact Magic Template summaries.

Copy ready-made Cursor and Claude Desktop configs from API & MCP.

Error handling

Failures before render never deduct credits

-32022 / HTTP 422: IMAGE_LOAD_FAILED — bad URL, non-image, private IP, or SSRF blocked. No credits charged.
-32033 / HTTP 502: HEADLESS_RENDER_FAILED — Chromium/WebGL or FFmpeg pipeline error. No credits charged.
-32602 / HTTP 400: validation errors (unknown template, video without mode: "3d", etc.).

Credit metering

Recorded after a successful render

Static 2D/3D PNG renders: 1 credit
Animated MP4 / GIF / WebM video renders: 3 credits

Limits

Enforced per account and per API key

Per-key rate limit: 60 requests / minute (default)
Standard plan quota: 500 renders / month
Autonomous plan quota: 5,000 renders / month