Mockup API

Authentication

All API requests require an API key sent in the Authorization header.

Authorization: Bearer your_api_key

Keys are provisioned manually for compatibility-approved private pilots. Self-service signup is not available. Keep the assigned key secret.

Generate mockup

Composite one or more images into a PSD template. Provide a PSD URL. Managed revisions are a preview contract and will require an assigned, activated revision. The API detects smart object placeholder layers, perspective-transforms your images into them, and returns a download URL for the finished PNG.

Request body

# Single-image mockup
curl -X POST https://api.printed.app/api/v1/process \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "psdUrl": "https://your-cdn.com/templates/frame-mockup.psd",
    "imageUrls": ["https://your-cdn.com/images/poster.png"],
    "imageFit": "cover"
  }'

Response

{
  "success": true,
  "resultUrl": "https://storage.printed.app/outputs/2025-01-15T12-30-abc.png?sig=...",
  "expiresIn": 3600,
  "processingTimeMs": 4523
}

{
  "success": false,
  "error": "PSD \"template.psd\" expects 2 poster(s) but only 1 image(s) provided.",
  "processingTimeMs": 1234
}

Health check

Returns API status. No authentication required.

{ "status": "ok", "version": "1.0.0" }

Code examples

Full working examples in popular languages. Replace your_api_key with your actual key.

async function generateMockup(psdUrl, imageUrls) {
  const response = await fetch('https://api.printed.app/api/v1/process', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your_api_key',
    },
    body: JSON.stringify({ psdUrl, imageUrls }),
  });

  const data = await response.json();

  if (!data.success) {
    throw new Error(`Mockup failed: ${data.error}`);
  }

  // Download the result to your own storage
  const image = await fetch(data.resultUrl);
  const buffer = await image.arrayBuffer();

  // Save or upload to your CDN
  fs.writeFileSync('mockup.png', Buffer.from(buffer));

  return data.resultUrl;
}

import requests

def generate_mockup(psd_url: str, image_urls: list[str]) -> str:
    response = requests.post(
        'https://api.printed.app/api/v1/process',
        headers={
            'Authorization': 'Bearer your_api_key',
            'Content-Type': 'application/json',
        },
        json={
            'psdUrl': psd_url,
            'imageUrls': image_urls,
        },
        timeout=120,
    )

    data = response.json()

    if not data.get('success'):
        raise Exception(f"Mockup failed: {data.get('error')}")

    # Download the result
    img = requests.get(data['resultUrl'])
    with open('mockup.png', 'wb') as f:
        f.write(img.content)

    return data['resultUrl']

$ch = curl_init('https://api.printed.app/api/v1/process');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer your_api_key',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'psdUrl' => 'https://your-cdn.com/templates/frame.psd',
        'imageUrls' => ['https://your-cdn.com/images/poster.png'],
    ]),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['success']) {
    // Download result
    file_put_contents('mockup.png', file_get_contents($response['resultUrl']));
}

# Generate a mockup
curl -X POST https://api.printed.app/api/v1/process \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "psdUrl": "https://your-cdn.com/templates/frame-mockup.psd",
    "imageUrls": ["https://your-cdn.com/images/poster.png"]
  }'

# Download the result
curl -o mockup.png "PASTE_RESULT_URL_HERE"

Multi-image mockup

For PSD templates with multiple placeholder slots (e.g., a gallery wall with 3 frames), provide one image URL per slot:

curl -X POST https://api.printed.app/api/v1/process \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "psdUrl": "https://your-cdn.com/templates/gallery-3-frame.psd",
    "imageUrls": [
      "https://your-cdn.com/images/left-poster.png",
      "https://your-cdn.com/images/center-poster.png",
      "https://your-cdn.com/images/right-poster.png"
    ],
    "psdIdentifier": "Gallery Wall 3-Frame.psd"
  }'

PSD templates

Your PSD templates must use smart object layers as image placeholders. The API automatically detects these and composites your artwork into them with perspective correction.

Requirements

Tips

• Name placeholder layers clearly — layers named "INPUT" or "Change Poster" are auto-detected
• Test with one template first before processing in bulk
• Match image count to placeholder slots exactly
• Use psdIdentifier if your URL uses a hashed or obfuscated filename
• PNG input images are recommended for best quality

Hosting your files

You host your own PSD templates and input images. They just need to be accessible via HTTPS URL.

The signed result URL expires after 1 hour. URL expiry does not delete the object; each pilot agreement defines storage retention and deletion.

Pilot performance

Local saved-composite checks and repeatability runs do not establish hosted latency or throughput. Historical Fly figures are not a service-level promise for the Vercel Sandbox deployment.

Rate limits

If you hit the rate limit, you'll receive a 429 response. Wait a moment and retry.

Error handling

Always check the success field in the response body, even on 200 status codes.

HTTP status codes

Retry strategy

Most errors are deterministic (bad PSD, wrong image count) and won't resolve on retry. Only retry on 500 or timeout.

Attempt 1: immediate
Attempt 2: wait 2 seconds
Attempt 3: wait 5 seconds