Mockups Generator
API reference.

Quickstart: submit JSON, track the job, download the image

Use the same HTTPS origin as your workspace, followed by /api/v1. Create an API key under API access. Upload or choose a ready template, inspect its slots, and replace the template, asset and slot placeholders below with your own IDs. Public library templates can be rendered directly when their status is ready. Treat all job IDs as opaque strings.

POST /api/v1/render-jobs accepts application/json, multipart/form-data and URL-encoded form fields. With JSON, options is an object. With form data, options is a JSON-encoded string. HTTP 202 means the job was accepted, not that its image is ready. A fast job may already be done in the acceptance response. Save id before doing anything else.

Read GET /api/v1/render-jobs/{job_id} until status is done, error or cancelled. Download GET /api/v1/render-jobs/{job_id}/result with the same bearer credential. Start with a five-second delay and impose a deadline. Long render times do not require resubmitting the job.

curl "$BASE_URL/api/v1/render-jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-artwork-v1" \
  --data '{"template_id":"REPLACE_TEMPLATE_ID","options":{"format":"png","mode":"full","slots":{"REPLACE_SLOT_ID":{"asset_id":"REPLACE_ASSET_ID","fit":"contain"}}}}'

# Save the response id, then check status:
curl -H "Authorization: Bearer $API_KEY" "$BASE_URL/api/v1/render-jobs/$JOB_ID"
# Once status is done, download using an authenticated client:
curl -L -H "Authorization: Bearer $API_KEY" "$BASE_URL/api/v1/render-jobs/$JOB_ID/result" -o mockup.png

• Create an API key
• Choose a template

Authentication, account usage and key management

Send Authorization: Bearer soe_YOUR_KEY from your server or automation platform. Store keys in its credential store, not in shared workflow JSON. Shared workspace endpoints accept either this header or a signed-in browser session. Public library, output profiles, billing plans and fixed demo endpoints do not require a key. The endpoint inventory below identifies the authentication boundary for every resource.

GET /api/auth/me accepts bearer authentication as well as a session. It returns plan, usage.used, usage.allowed and limits. Administrator accounts receive null for unlimited subscription allowances and limits. This response also contains your webhook_secret and website_key: keep it private and avoid logging or exporting it. GET /api/v1/dashboard returns only your workspace counts and recent resources. API usage and editor exports use the same account allowance.

POST /api/v1/keys with a JSON name creates a key and returns its full value once. GET lists key metadata; DELETE /api/v1/keys/{key_id} revokes one key. POST /api/v1/keys/webhook-secret and /website-key rotate account secrets. Rotation affects existing integrations. Billing checkout, portal and sync are session flows; provider webhooks are verified provider callbacks. Admin routes require an admin session and are not customer automation endpoints.

GET /api/auth/me
Authorization: Bearer soe_YOUR_KEY

POST /api/v1/keys
Content-Type: application/json
{"name":"n8n production"}

Connect n8n, Make, Zapier, Airtable and Power Automate

For automation, prefer a JSON background job followed by authenticated status checks and a separate file download. This works with generic HTTP clients and avoids treating binary image data as JSON. These are custom HTTP workflows, not published native Mockups Generator marketplace apps.

Use asset_id for artwork already in your workspace, or design_url for a direct, publicly fetchable image URL. A Drive sharing page, a Dropbox preview, an Airtable viewer URL or a link needing cookies is not a direct image. Fresh Airtable attachment download URLs expire; import reusable artwork into assets before scheduling repeated runs. Remote URLs must resolve to permitted public addresses and cannot supply additional authentication headers.

Every platform has its own timeouts, credential controls, file handling and plan requirements. The guides below include exact mappings, recovery steps and downloadable resources. Relay.app closed in September 2026; its guide covers migrating recovered configurations rather than creating a new Relay workflow.

• n8n guide and workflows
• Make HTTP scenario guide
• Zapier API and webhook guide
• Airtable automation scripts
• Power Automate and custom connector
• Relay.app migration guide

Templates, background PSD imports and layer setup

POST /api/v1/templates uploads file plus optional name as multipart and returns 201. Prefer POST /api/v1/templates/imports for background PSD processing: it returns 202 with an import ID. List imports, read /imports/{job_id}, and use its cancel or retry action as needed. Wait for the import to expose its template_id and for the template to become ready. Import completion can still require layer setup.

GET /api/v1/templates lists your templates; GET /{template_id} also reads an accessible public template. GET /{template_id}/layers inspects an owned PSD's layer manifest and compatibility report. PUT /{template_id}/layers selects design_layer_ids and color_layer_ids, configures bindings, records acknowledged warnings and increments the template revision. A template in needs_setup cannot be rendered. Ownership is required to modify or delete a template.

Choose artwork areas and supported product color controls separately. A layer cannot be both. Slot keys can be layer IDs, unique IDs or unambiguous names; layer IDs avoid duplicate-name ambiguity. Nested targets use their canonical path IDs. Read the returned compatibility report, including approximate and unsupported effects, before approving output.

GET /api/public/library supports q, category, sort, limit and offset; its response includes templates and total. GET /library/{template_id} and /related expose public detail and related scenes. Retrieve every page when selecting an entire catalog, rather than assuming the first page is complete.

PUT /api/v1/templates/REPLACE_TEMPLATE_ID/layers
{"name":"Tee front and back","design_layer_ids":["12","34"],"color_layer_ids":["56"],"bindings":{"34":{"mode":"linked","source":"12","inherit_placement":false}},"acknowledge_warnings":false}

Design assets, folders, search and ordering

POST /api/v1/assets uploads a PNG, JPEG or WebP file as multipart, with optional folder_id. The per-file size limit defaults to 30 MB and can be configured by the operator. The JSON response contains id, name, width, height, thumb_url and other asset metadata. Saved artwork stays scoped to its owner.

GET /api/v1/assets supports limit (1 to 500), offset, q, folder_id, orientation (portrait, landscape or square) and sort (natural, saved or newest). Its envelope contains assets, total, offset, limit and has_more. Increase offset by the returned page length until has_more is false. Use folder_id=unfiled to list unfiled artwork.

GET and POST /api/v1/assets/folders list and create folders. PATCH /folders/{folder_id} changes name or position; DELETE removes the folder and returns its artwork to unfiled. PATCH /{asset_id} renames, moves or sets sort_order. POST /move accepts asset_ids and folder_id, including null for unfiled. POST /order preserves the supplied order, then appends remaining folder artwork. DELETE /{asset_id} deletes an owned asset.

GET /media/assets/{asset_id} returns the original file and /thumb returns its thumbnail, both with bearer authentication. Use asset_id in render options instead of passing a protected media URL as design_url.

POST /api/v1/assets/folders
{"name":"Approved summer artwork","position":0}

POST /api/v1/assets/move
{"asset_ids":["REPLACE_ASSET_ID"],"folder_id":"REPLACE_FOLDER_ID"}

Synchronous renders, editor previews and paid exports

POST /api/v1/renders accepts the same JSON or form request as a background render and returns image bytes. Read X-Render-Id and X-Render-Ms. Every successful synchronous render is a paid export against your allowance. store=true retains its result for later authenticated retrieval; otherwise download the immediate response. This endpoint does not provide idempotent submission, so a blind retry after a lost response may create another paid render.

POST /api/v1/templates/{template_id}/editor-render is the preview endpoint when store=false (the default). It returns image bytes from a downscaled preview without charging an export. store=true returns JSON with image_url, render_id, ms and export, and charges an export. Prefer POST /{template_id}/editor-export for a durable background export with an Idempotency-Key header. Its body can omit template_id because the path identifies the template.

Supply artwork as an uploaded multipart part named after the slot, options.slots.<slot>.asset_id, or options.slots.<slot>.design_url. Uploaded bytes take precedence, then a URL reference is resolved before an asset reference. Avoid supplying competing inputs. A slot can instead use a color fill or retain_original=true. All JSON requests follow the same layer, ownership, remote-fetch and quota checks as file uploads.

# File upload keeps the existing multipart contract:
curl "$BASE_URL/api/v1/renders" -H "Authorization: Bearer $API_KEY" \
  -F "template_id=$TEMPLATE_ID" -F "Front Design=@artwork.png" \
  -F 'options={"format":"png","mode":"full"}' -o mockup.png

Render options and slot adjustments

Use options as a JSON object, or encode it once as a form string. Nested options override simple fields such as fit or format. Numeric bounds below describe the renderer's clamping behavior. Defaults are cover, PNG, quality 90, supersample 2, scene background and full mode. Preserve a reviewed template's accepted settings when automating.

full recomposes supported PSD layers and effects. fast uses a flattened approximation and is not equivalent to full PSD composition. allow_approximate=true acknowledges a supported approximation; it does not implement an unsupported Photoshop effect. Inspect a representative final export, not just a small preview.

An explicit bindings graph uses independent or linked mode, a source design-area ID, an optional role and inherit_placement. It controls artwork assignment separately from PSD smart-object source sharing. Omitting bindings uses template defaults; an explicit empty graph separates the selected areas. retain_original is supported in full scene output, not in transparent artwork-only output.

Job states, idempotency and recovery

Background render status includes id, status, stage, completed, total, mode, template_id, error, duration_ms, created_at and result_url. queued, running and cancelling are nonterminal; done, error and cancelled are terminal. A render result is available only when done. Polling, webhook delivery and downloading a result do not create another render.

Use an Idempotency-Key header of 1 to 200 characters on POST /render-jobs and /templates/{template_id}/editor-export. Derive it from the source record plus an artwork or operation version. Retrying identical inputs with the same key returns the same job. Changing inputs with that key returns 409. Persist both the key and job ID outside the automation run so restarts retain them.

GET /render-jobs?limit=25 returns recent jobs, capped at 100. POST /render-jobs/{job_id}/cancel requests a stop; an in-progress render may finish. POST /render-jobs/{job_id}/retry resumes a recoverable failed job and returns 202. Read status after either action. Use the existing job's recovery controls rather than generating a replacement job with a new key.

Signed webhooks, delivery history and safe receivers

POST /api/v1/render-jobs and POST /api/v1/bulk-jobs accept webhook_url for a permitted public HTTP(S) receiver. Prefer HTTPS. Background editor-export does not retain a webhook_url; poll that job instead. Events are render.completed, render.failed, render.cancelled, bulk.completed, bulk.failed and bulk.cancelled. Payloads include a stable event_id, event, created_at, id, status and result fields. There is no custom webhook-header authentication setting.

X-MGW-Signature contains hex HMAC-SHA256 of the exact raw body using your account signing secret. X-MGW-Event identifies the event and X-MGW-Delivery identifies the delivery. Check the signature before processing; parsing and reserializing JSON changes the signed bytes. Deduplicate event_id and correlate id with a job you submitted. Return a 2xx response promptly, within the sender's eight-second timeout.

Network timeouts and HTTP 408, 425, 429 or 5xx are eligible for up to eight delivery attempts. Other unsuccessful responses require review. GET /api/v1/webhook-deliveries exposes delivery history; POST /{identifier}/retry replays a delivery using the same event identity. Current account signing secrets are used on each attempt, including after rotation.

If your automation cannot inspect the raw body and signature headers, use authenticated polling as the simplest verified completion path. A catch-webhook can also be an untrusted wake-up signal: look up a previously stored job ID with your bearer key and verify its state before changing records. Never fetch an arbitrary callback URL supplied by an incoming payload or infer ownership from an unsigned notification.

import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, signature, secret) {
  if (typeof signature !== "string" || !/^[a-f0-9]{64}$/i.test(signature)) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature, "hex"));
}

Small synchronous batches

POST /api/v1/renders/batch accepts a JSON object with batch, an array of 1 to 50 items. Each item has template_id, optional label, options and, for multipart uploads, a designs map from slot keys to uploaded field names. JSON clients should use asset_id or design_url in options.slots.

This endpoint completes work inside the request. Its JSON envelope contains total, successful, failed and renders. Each item reports status, label and either render_id plus url, or an error. A 200 response can contain failures, so check each item. Successful results use one render credit each. Prefer bulk jobs for longer runs, recoverable collections and ZIP downloads. Synchronous batch submissions do not accept an idempotency key.

{"batch":[{"template_id":"REPLACE_TEMPLATE_ID","label":"front","options":{"slots":{"REPLACE_SLOT_ID":{"asset_id":"REPLACE_ASSET_ID"}}}}]}

Collections and reviewed artwork assignments

POST /api/v1/bulk-jobs/preflight accepts JSON or multipart spec plus uploaded artwork. It reports valid, errors, warnings, total, credits_required, items and per-template summary. HTTP 200 does not mean valid is true. Inspect the intended image count, every physical artwork assignment and representative samples before paying for a large collection. Jobs are limited to 1000 planned images and the available account allowance.

The current assignment model puts areas on each templates entry. Area mode pool accepts asset_ids or folder_ids; fixed uses asset_id; shared uses another area as source; original retains PSD artwork. generation.mode is together, distribute, random or combinations. Settings can include count, seed, balanced, unique_designs, unique_outputs and exclude_fixed. repeats is a positive integer or a map of variable artwork inputs to repeat counts, supported by together and random generation. Feasibility is checked by preflight. Per-template generation overrides the global setting. Independent templates add their output counts rather than cross-multiplying each other.

Assignment preflight returns plan_id, plan_hash and expires_at. GET /api/v1/bulk-jobs/plans/{plan_id} restores the reviewed plan and rechecks current allowance. POST /bulk-jobs/sample with the saved token and optional index query returns a free, reduced-size image. Submit the approved plan as only plan_id, plan_hash, idempotency_key and optional webhook_url or continue_on_error. Do not merge new assignments or options into that token. Changed or expired reviews return 409 and need a fresh review.

Keep the accepted plan token unchanged across submission retries. A new preflight can create a different plan_id even for similar inputs, so submitting its new token with an existing idempotency_key can return 409. Persist the accepted token and job ID with the business record. Once a submission was accepted, retrying its identical token and key returns the existing job, including after the review later expires.

The legacy collection spec remains available: templates, assets or explicit design_sets with role_slots, colors, options, project_id/project_revision and optional template expected_revision. Product color variants require authored product-color controls; color_mode=artwork deliberately fills artwork areas instead. Simple assets default to an artwork area and cannot express independent pools on several areas. Use the reviewed areas model for the app's current multi-artwork workflow.

GET /bulk-jobs/{bulk_id} includes status, stage, total, completed, failed, credits_used, items and has_result. POST /cancel stops future work; POST /retry retries failed items, with include_cancelled=true as a query option to continue stopped work. Only newly successful images consume credits. GET /result downloads the ZIP, /manifest returns JSON and /items/{item_id}/result returns one finished image. A failed or cancelled collection may still have a partial ZIP: reconcile its manifest instead of assuming every image succeeded.

// First: POST /api/v1/bulk-jobs/preflight
{
  "templates":[{"id":"REPLACE_TEMPLATE_ID","areas":{
    "REPLACE_FRONT_SLOT_ID":{"mode":"pool","asset_ids":["REPLACE_ASSET_ID"]},
    "REPLACE_BACK_SLOT_ID":{"mode":"shared","source":"REPLACE_FRONT_SLOT_ID"}
  }}],
  "generation":{"mode":"combinations","seed":"approved-order-1042"},
  "options":{"format":"png","output_profile":"gallery-square-v1"}
}
// After reviewing valid, warnings, items and the sample:
// POST /api/v1/bulk-jobs
{"plan_id":"REPLACE_PLAN_ID","plan_hash":"REPLACE_PLAN_HASH","idempotency_key":"order-1042-collection-v1"}

• n8n collection walkthrough
• Worked collection files

Saved projects, versions and placement presets

GET /api/v1/projects filters kind (editor or collection), template_id, archived and limit. POST creates a JSON recipe with name, kind, state and, for an editor, template_id. Use the editor's saved recipe shape, not a render request, as state. Supported state versions are 1 and 2; referenced templates, artwork, folders and bindings are validated. Project state is capped at 250 KB.

GET /projects/{identifier} returns state, dependencies, revision and warnings. PUT saves the full recipe with expected_revision for optimistic locking. POST /archive uses archived and expected_revision. A 409 means a revision or dependency changed; reload and review before overwriting. GET /versions and /versions/{revision} read history. POST /duplicate copies a recipe; POST /collection transfers an editor recipe into a collection with its placements. Exporting a project uses the render or bulk APIs, not a project mutation.

POST /api/v1/presets stores template_id, name and slots. GET /presets optionally filters template_id; DELETE /presets/{preset_id} removes one. Apply preset_id in a legacy collection template entry, or copy its slots into render options. Collection profiles are saved projects of kind collection, not a separate /profiles API. GET /api/public/output-profiles lists fixed listing-output profiles, which are a different resource.

PUT /api/v1/projects/REPLACE_PROJECT_ID
{"name":"Reviewed tee recipe","kind":"editor","template_id":"REPLACE_TEMPLATE_ID","state":{"version":1,"slots":{},"format":"png"},"expected_revision":2}

Physical print checks and flat PNG exports

POST /api/v1/renders/print-preflight accepts the render input plus print_profile: width_mm, height_mm, dpi (72..1200), bleed_mm, safe_area_mm and optional background (any or transparent). Its JSON report includes physical dimensions, required pixels and warnings for the supplied artwork. Preflight is free and is not a guarantee of printer acceptance.

POST /renders/print-files exports each supplied artwork area flat, without the product scene or perspective warp, at its source pixel dimensions. It returns print_files with slot, target_id, width, height, dpi and authenticated url, plus report when a profile is provided. One render credit is used per successful flat file. Increasing image_dpi changes metadata, not the pixel count.

When the report has warnings, inspect them and the supplier requirements before passing acknowledge_print_warnings=true. Use a JSON boolean in JSON requests and the literal string true in form data. image_dpi defaults to 300 when no physical profile is supplied; a supplied profile's dpi takes precedence. These are synchronous operations without submission idempotency, and flat print files are not included automatically in collection ZIPs.

{"template_id":"REPLACE_TEMPLATE_ID","options":{"slots":{"REPLACE_SLOT_ID":{"asset_id":"REPLACE_ASSET_ID"}}},"print_profile":{"width_mm":254,"height_mm":304.8,"dpi":300,"bleed_mm":3,"safe_area_mm":5,"background":"any"}}

• Actual print preflight report

AI artwork, product-photo templates and segmentation

GET /api/v1/ai/models lists enabled model IDs, names and kind. POST /api/v1/ai/generate accepts model_id and prompt, then returns provider image URLs and the first generated image as an owned asset. Availability depends on the operator's enabled model and provider configuration. This call is synchronous and has no submission idempotency, so do not automatically repeat it after an ambiguous timeout.

POST /api/v1/templates/from-image accepts form fields quad (JSON four normalized [x,y] corners in top-left, top-right, bottom-right, bottom-left order), optional name, slot_name, auto_mask and mask_b64, plus either an uploaded image file or asset_id. It returns a customizable image-based template. POST /templates/segment accepts asset_id and optional points (JSON normalized [x,y,label] triples, with 1 keep and 0 remove). It returns engine, mask and quad, possibly null when no product is detected. POST /templates/suggest-print-area accepts asset_id and returns quad and maskable.

These photo-creation and segmentation endpoints still use form fields. Choose URL-encoded fields when using asset_id, or multipart when uploading a file. Review suggested geometry and masks before rendering; detection is not an approval of the printable region. AI model administration is an admin-session operation, separate from customer API access.

POST /api/v1/ai/generate
{"model_id":"REPLACE_ENABLED_MODEL_ID","prompt":"A clean white tee product scene"}

# Use the returned asset.id with from-image form fields:
asset_id=REPLACE_ASSET_ID
quad=[[0.25,0.2],[0.75,0.2],[0.75,0.7],[0.25,0.7]]
slot_name=Design

Embedded editor and website keys

POST /api/v1/keys/website-key issues a client-visible website key scoped to the issuing account's own templates. Embedded requests use X-Website-Key or the wk query parameter, not a bearer API key. GET /api/embed/templates/{template_id} reads template metadata, GET /preview supplies the preview and POST /render runs the embedded editor flow.

Place /embed/{template_id}?wk=YOUR_WEBSITE_KEY in an iframe on your website. Customers can preview without creating a new account, while completed exports consume the owner's allowance. The frame communicates its exported result through postMessage. Check the event's origin and source before acting; a website key is not a credential for assets, projects, collections or account management. Review the embed guide before exposing a production template.

<iframe src="https://web.mockupsgenerator.com/embed/REPLACE_TEMPLATE_ID?wk=REPLACE_WEBSITE_KEY" title="Customize your product" width="100%" height="700"></iframe>

• Embedded editor capabilities

Result URLs, redirects and file destinations

Authenticated result and media routes are not public file-sharing links. A no-code upload module, email service or Airtable attachment field usually cannot send your bearer key when fetching a URL. Download the bytes with an authenticated HTTP action and upload those bytes to the destination's file action, or copy the file to storage that provides an appropriate accessible URL.

result_url can be a relative API route or a temporary presigned storage URL. Resolve relative paths against your API origin. For predictable authentication, use the canonical /render-jobs/{job_id}/result or /bulk-jobs/{bulk_id}/result path. It may respond with 307 to a signed storage download. Follow redirects without forwarding the bearer key to a different origin. Refresh status or call the result endpoint again when a signed link expires.

Stored outputs remain associated with the account, but temporary download URLs have their own expiry and resources can be deleted. Keep important delivered files in your destination storage. Public template preview routes are public only when the template is public; private previews, design originals, thumbnails and render outputs require an authorized owner.

Errors, retries, quotas and request limits

Errors use a JSON detail field, which may be a string, a structured object or a validation array. HTTP 401 means missing or revoked authentication; 404 can mean the resource is not accessible to your account. HTTP 409 covers not-ready results, changed inputs, stale project revisions and expired reviews. Inspect detail before deciding which kind of conflict occurred.

HTTP 413 means an upload or stored project is too large. HTTP 422 means invalid options, geometry, artwork or print warnings. Quota limits return 402; replenish allowance or reduce the reviewed workload rather than retrying immediately. HTTP 429 indicates a rate limit. Network failures, 408, 425, 429 and 5xx can be retried with bounded backoff for reads and idempotent job submissions. Check Retry-After when supplied, but the API does not promise that header on every failure.

Set a deadline and an error branch. Do not retry authentication, ownership or validation failures unchanged. Preserve one idempotency key for one intended operation. Avoid blind retries on synchronous renders, batches, AI generation and print exports, which have no submission deduplication. A polling deadline stops your workflow's waiting; it does not cancel the server job.

Output width is capped at 8192, small batches at 50 items and collections at 1000 planned images. Account template, PSD and artwork allowances vary by plan; inspect /api/auth/me. Upload limits are operator-configured. Bulk multipart uploads also enforce a 200 MB aggregate request limit. Use the live OpenAPI explorer for exact query parameters, body schemas and deployment-specific availability.

• Current account plans
• Live OpenAPI explorer
• Download live OpenAPI JSON