mockup-generator

Multi-provider mockup generation for merch products. Default free path via Printful API, optional Dynamic Mockups for custom PSD templates, SudoMock for high volume. Generates t-shirt, hoodie, sticker, and lifestyle mockups.

Model	Source
sonnet	pack: merch

Full Reference

┏━ 🔧 mockup-generator ━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ [one-line description of mockup generation task] ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Overview

Shared utility for all merch lanes. Takes a design PNG and generates realistic product mockups. Routes to the best provider based on the product type and requirements. Default path is Printful (free for catalog products).

Quick Reference

Item	Value
Default Provider	Printful Mockup API (free)
Alternative 1	Dynamic Mockups ($0.051/render, custom PSD templates)
Alternative 2	SudoMock ($0.002/render, high volume)
DIY Option	ImageMagick + displacement maps (self-hosted)
Input	PNG with transparent background, 300 DPI recommended
Output	JPEG or PNG mockup image

Reference Index

File	Contents
reference/providers.md	Printful Mockup API, Dynamic Mockups API, SudoMock API, ImageMagick DIY — endpoints, request formats, batch support, pricing

Provider Routing

Need	Provider	Cost	Speed
Printful catalog product	Printful Mockup API	Free	Async (2-30s)
Custom PSD template (lifestyle)	Dynamic Mockups API	$0.051/render	Sync (<1s)
High volume batch (100+)	SudoMock API	$0.002/render	Parallel
Self-hosted / no API dependency	ImageMagick + displacement maps	Infra only	Instant

Default: Always try Printful first. It’s free and covers most catalog products (t-shirts, hoodies, hats, stickers, tote bags).

Flow

1. Receive design PNG + product type + options
   ↓
2. Select provider
   → Printful catalog product? → Printful API
   → Custom PSD template? → Dynamic Mockups
   → 100+ renders? → SudoMock
   → No API available? → ImageMagick DIY
   ↓
3. Generate mockup(s)
   → Printful: POST /v2/mockup-tasks, poll for completion
   → Dynamic Mockups: POST /v1/renders, get result immediately
   → SudoMock: POST concurrent requests
   ↓
4. Return mockup image(s)
   → URL or local file path
   → Multiple colorways if requested

File Requirements

Input:

• PNG with transparent background
• 300 DPI recommended (150 DPI minimum for apparel)
• sRGB color profile
• Design dimensions should match product print area

Output:

• JPEG (default, smaller file size) or PNG (if transparency needed)
• Resolution depends on provider (Printful: typically 1000x1000px)
• Multiple outputs for multi-color requests

Batch Support

Provider	Batch Method	Speed
Printful	Multiple variant IDs in one mockup task (all colors at once)	One request, one poll
Dynamic Mockups	Up to 30 images in ~4 seconds	Parallel processing
SudoMock	1-25 concurrent requests (plan-dependent)	Parallel

Integration

• Called by: printful-pod, sticker-forge, premium-gear
• Depends on: Provider API keys in .env (Printful: PRINTFUL_TOKEN, Dynamic Mockups: DYNAMIC_MOCKUPS_API_KEY, SudoMock: SUDOMOCK_API_KEY)
• Note: Only PRINTFUL_TOKEN is required. Other providers are optional upgrades.