Generate Mockup

Generate a device mockup from a screenshot.

POST /api/v1/mockup

Request

Headers

Header	Value	Required
Authorization	Bearer YOUR_API_KEY	Yes
Content-Type	application/json	Yes

Body Parameters

Parameter	Type	Required	Description
type	string	Yes	Request type. Must be "screenshot"
screenshot	object	Yes	Screenshot source configuration
screenshot.type	string	Yes	Source type: "url" or "base64"
screenshot.src	string	Yes	URL or base64-encoded image data
settings	object	No	Render settings (see below)
fast	boolean	No	Enable faster rendering (lower quality)

Query Parameters

Parameter	Default	Description
output	json	Response format: json or raw

When output=raw, the response is the raw image bytes instead of JSON.

Settings Object

{
  "settings": {
    "device": "iphone-15-pro-max",
    "appearance": {
      "backgroundColor": "#1a1a2e",
      "gradientEnabled": true,
      "gradientColor": "#16213e",
      "deviceColor": "#000000"
    },
    "deviceTransform": {
      "scale": 1.0,
      "positionY": 0,
      "rotationX": 0,
      "rotationY": 0
    },
    "shadow": {
      "enabled": true,
      "opacity": 0.5,
      "blur": 5,
      "color": "#000000"
    },
    "reflection": {
      "enabled": true,
      "intensity": 1.0,
      "environment": "studio"
    },
    "postProcessing": {
      "bloom": false,
      "vignette": false,
      "grain": false
    },
    "export": {
      "format": "png",
      "quality": 90,
      "scale": 2
    }
  }
}

See the Settings section for detailed documentation on each option:

• Devices
• Appearance
• Transform
• Effects
• Export

Response

JSON Response (default)

{
  "success": true,
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "width": 1920,
    "height": 1080
  },
  "duration": 2340
}

Field	Type	Description
success	boolean	Always true for successful requests
image.data	string	Base64-encoded image data
image.mimeType	string	image/png, image/jpeg, or image/webp
image.width	number	Image width in pixels
image.height	number	Image height in pixels
duration	number	Render time in milliseconds

Raw Response

When ?output=raw is specified, the response is the raw image bytes with appropriate headers:

Header	Description
Content-Type	Image MIME type
X-Duration-Ms	Render time in milliseconds

Examples

Minimal Request

curl -X POST https://shotprose.com/api/v1/mockup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "screenshot": {
      "type": "url",
      "src": "https://example.com/screenshot.png"
    }
  }'

With Custom Settings

curl -X POST https://shotprose.com/api/v1/mockup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "screenshot": {
      "type": "url",
      "src": "https://example.com/screenshot.png"
    },
    "settings": {
      "device": "iphone-15-pro-max",
      "appearance": {
        "backgroundColor": "#1a1a2e",
        "gradientEnabled": true,
        "gradientColor": "#16213e"
      },
      "shadow": {
        "enabled": true,
        "opacity": 0.6
      },
      "export": {
        "format": "png",
        "quality": 95,
        "scale": 2
      }
    }
  }'

Raw Image Output

curl -X POST "https://shotprose.com/api/v1/mockup?output=raw" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "screenshot": {
      "type": "url",
      "src": "https://example.com/screenshot.png"
    }
  }' \
  --output mockup.png

Base64 Input

curl -X POST https://shotprose.com/api/v1/mockup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "screenshot": {
      "type": "base64",
      "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }'

Error Responses

Code	Status	Description
INVALID_REQUEST	400	Invalid request body or missing screenshot
MISSING_AUTH	401	Authorization header missing
INVALID_API_KEY	401	API key is invalid or revoked
SUBSCRIPTION_REQUIRED	403	Active Pro subscription required
RATE_LIMITED	429	Rate limit exceeded
RENDER_TIMEOUT	504	Render operation timed out
RENDER_FAILED	500	Failed to generate mockup