Official Node.js/TypeScript SDK for the SudoMock API. Generate product mockups from Photoshop PSD files, or from a product photo without any PSD.
npm install sudomockRequirements: Node.js 20+ (uses native fetch)
import SudoMock from 'sudomock'
const client = new SudoMock('sm_your_api_key')
// or set SUDOMOCK_API_KEY env var and call: new SudoMock()
// List your mockups
const { mockups, total } = await client.psdMockups.list({ limit: 10 })
console.log(`Found ${total} mockups`)
// Render a mockup with artwork
const render = await client.renders.create({
mockupId: mockups[0].uuid,
smartObjects: [{
uuid: mockups[0].smartObjects[0].uuid,
asset: { url: 'https://example.com/design.png' },
}],
exportOptions: { imageFormat: 'webp', imageSize: 1080 },
})
console.log(render.url) // https://cdn.sudomock.com/renders/...import SudoMock from 'sudomock'
const client = new SudoMock('sm_xxx', {
baseUrl: 'https://api.sudomock.com', // default
timeout: 30_000, // default (ms)
maxRetries: 2, // default
})The API key can be passed as the first argument or via the SUDOMOCK_API_KEY environment variable.
Every request identifies itself with X-SudoMock-Client: node-sdk/<version> (and the same value as User-Agent where the runtime allows it), so you can pick the SDK's traffic out of your own logs and proxy rules.
client.ai and client.mockups are the earlier names of client.photoMockups
and client.psdMockups. Each stays on the endpoint it was published on, so an
async job you open through an earlier name comes back under the 2d_* kind it
always did, and each warns once per process. Switch to client.photoMockups /
client.psdMockups to move to the family paths and the photo_mockup_* kinds.
Both earlier names accept assignment, so a test double can replace them.
// List mockups with pagination and filtering
const result = await client.psdMockups.list({
limit: 20,
offset: 0,
name: 'shirt', // case-insensitive contains
sort: 'created_at', // 'name' | 'created_at' | 'updated_at'
order: 'desc', // 'asc' | 'desc'
})
// Get a single mockup
const mockup = await client.psdMockups.get('uuid')
console.log(mockup.smartObjects)
// List every layer, nested as in Photoshop's Layers panel
const { layers } = await client.psdMockups.layers('uuid')
// Update mockup name
const updated = await client.psdMockups.update('uuid', { name: 'New Name' })
// Delete a mockup
await client.psdMockups.delete('uuid')Bulk delete all mockups (
DELETE /api/v1/psd-mockups/all) requires a dashboard Bearer token and is not callable with an API key (the API returns 403). It is therefore intentionally not exposed by this SDK -- use the dashboard.
const render = await client.renders.create({
mockupId: 'mockup-uuid',
smartObjects: [{
uuid: 'smart-object-uuid',
asset: {
url: 'https://example.com/artwork.png',
fit: 'fill', // 'fill' | 'contain' | 'cover'
rotate: 0,
flipHorizontal: false,
flipVertical: false,
},
color: {
hex: '#ff0000',
blendingMode: 'multiply',
},
}],
exportOptions: {
imageFormat: 'webp', // 'png' | 'jpg' | 'webp' (default 'webp')
imageSize: 2048, // width in px, 100-10000 (default 2048), or 'original'
quality: 90, // 1-100 (default 90)
dpi: 300, // optional, 72-2400: print resolution metadata (opt-in)
},
exportLabel: 'my-render',
})
console.log(render.url) // convenience: first file URL
console.log(render.printFiles) // full arrayUse an editable text layer from the mockup response to create personalized
outputs. smartObjects is optional for text-only renders, and fit defaults to
'overflow'.
const mockup = await client.psdMockups.get('mockup-uuid')
const nameLayer = mockup.textLayers.find((layer) => layer.name === 'Customer Name')
if (!nameLayer?.isEditable) throw new Error('Customer Name is not editable')
const names = ['Aylin', 'Deniz', 'Mert']
const renders = await Promise.all(names.map((name) => client.renders.create({
mockupId: mockup.uuid,
textLayers: [{
uuid: nameLayer.uuid,
text: name,
font: 'Montserrat-Bold',
color: '#FFFFFF',
fit: 'overflow',
}],
})))
for (const render of renders) {
console.log(render.url)
for (const warning of render.warnings ?? []) console.warn(warning.code, warning.message)
}hiddenLayers leaves up to 50 layers out of a single render; the template
itself does not change. client.psdMockups.layers() lists every layer of the
template with its UUID, including the layers inside a smart object's contents.
Hiding a group hides every layer inside it, a layer hidden inside a smart
object is hidden in every copy of it, and hiddenLayers works on its own.
const { layers } = await client.psdMockups.layers('mockup-uuid')
const badge = layers.find((layer) => layer.name === 'Sleeve badge')
if (!badge) throw new Error('Sleeve badge not found')
const render = await client.renders.create({
mockupId: 'mockup-uuid',
hiddenLayers: [badge.uuid],
})Pass isAsync: true to enqueue a render instead of blocking. The API responds
with 202 Accepted and renders.create resolves with a Job (TypeScript
narrows the return type via overload). Poll it with client.jobs:
const job = await client.renders.create({
mockupId: 'mockup-uuid',
smartObjects: [{ uuid: 'so-uuid', asset: { url: 'https://example.com/art.png' } }],
isAsync: true,
})
console.log(job.jobId, job.status) // 'queued'
// Poll a single time:
const status = await client.jobs.retrieve(job.jobId)
// ...or wait until it finishes (succeeded | failed):
const done = await client.jobs.waitForJob(job.jobId, {
intervalMs: 2000, // default
timeoutMs: 300_000, // default; throws TimeoutError if exceeded
})
if (done.status === 'failed') throw new Error(done.error ?? 'render failed')
console.log(done.resultUrl)waitForJob does NOT throw on a failed job -- inspect status and error.
It throws TimeoutError only when the job is still running past timeoutMs.
List and page your jobs (keyset pagination, newest first). Filter by kind
(render | video | upload | 2d_create | 2d_render |
photo_mockup_create | photo_mockup_render) and/or mockupUuid. A
photo-mockup job is spelled photo_mockup_* when submitted on
/api/v1/photo-mockups (where client.photoMockups posts since 2.7.0) and
2d_* when submitted on the earlier /api/v1/sudoai/2d-mockups path;
filtering by either spelling returns both:
const { jobs, nextCursor } = await client.jobs.list({ kind: 'video', limit: 50 })
if (nextCursor) {
const next = await client.jobs.list({ cursor: nextCursor })
}renders.createVideo animates a mockup. It is always asynchronous and returns a
Job of kind 'video'. Credit cost scales with duration, audio, and the
automatically selected quality tier. Every account gets one video at no charge,
once, for the lifetime of the account. Unsupported durationSeconds values
return a 400.
const job = await client.renders.createVideo({
mockupId: 'mockup-uuid',
smartObjects: [{ uuid: 'so-uuid', asset: { url: 'https://example.com/art.png' } }],
video: { durationSeconds: 4, audio: false },
})
const done = await client.jobs.waitForJob(job.jobId)
console.log(done.resultUrl) // mp4 URLvideo.motion ('ambient' | 'showcase', default 'ambient') controls the
camera movement. You can also animate a raw image directly (no mockup) and
attach a per-call webhook:
const job = await client.renders.createVideo({
imageUrl: 'https://example.com/art.png', // raw-image mode
video: { durationSeconds: 4, motion: 'showcase' },
webhook: { url: 'https://example.com/hooks/sudomock' },
})Render artwork onto an existing 2D mockup (no PSD template) and manage your 2D
mockup catalog. client.photoMockups.render posts to
/api/v1/photo-mockups/{mockupId}/render (the mockup id lives in the path)
and costs 5 credits per call. Each print area must supply artworkUrl OR
color. Use uuid for a saved print area -- a bounded zone drawn on the
product -- or surfaceUuid for a product surface, both returned by
client.photoMockups.get(). A product can have both, and they are separate targets.
Placement follows the target, and sizing has one answer per request: a surface
takes a coverage percentage or an explicit width + height, a print area
takes a fit or an explicit width + height. Anchoring -- position,
offsetX, offsetY, rotation -- belongs to both. The types enforce it, so
handing one the other's dial does not compile.
const result = await client.photoMockups.render({
mockupId: 'mockup-uuid',
printAreas: [{
uuid: 'print-area-uuid',
artworkUrl: 'https://example.com/design.png',
adjustments: { opacity: 90, vibrance: 10, blur: 0 },
}],
exportOptions: { imageFormat: 'webp', imageSize: 2048, quality: 90 },
})
console.log(result.url) // first rendered file
console.log(result.renderUuid) // correlate with webhooks
console.log(result.printFiles[0].durationMs) // 2340
console.log(result.printFiles[0].exportFormat) // 'webp'Prefer to render in the background? Pass isAsync: true and render() resolves
with a Job of kind 'photo_mockup_render' (202 Accepted) you await with
jobs.waitForJob. A photo_mockup_render.succeeded /
photo_mockup_render.failed webhook also fires (2d_render.succeeded /
2d_render.failed on an endpoint that keeps the legacy event names).
const job = await client.photoMockups.render({
mockupId: 'mockup-uuid',
printAreas: [{
uuid: 'print-area-uuid',
artworkUrl: 'https://example.com/design.png',
}],
isAsync: true,
})
const done = await client.jobs.waitForJob(job.jobId)
if (done.status === 'failed') throw new Error(done.error ?? 'render failed')
console.log(done.resultUrl) // rendered file URLCreate a reusable 2D mockup, then render artwork. By default creation is
synchronous: create() resolves with the ready mockup (including its
quads). Creation costs 25 credits. If the source image is unsuitable, the
25 credits are refunded automatically.
const mockup = await client.photoMockups.create({
sourceUrl: 'https://example.com/product.jpg',
name: 'Front view',
idempotencyKey: 'front-view-v1',
})
const printArea = mockup.quads[0]
if (!printArea) throw new Error('No print area available')
const result = await client.photoMockups.render({
mockupId: mockup.mockupId,
printAreas: [{
uuid: printArea.printAreaId,
artworkUrl: 'https://example.com/design.png',
}],
})
console.log(result.url)
const fullSurface = mockup.surfaces[0]
if (fullSurface) {
await client.photoMockups.render({
mockupId: mockup.mockupId,
printAreas: [{
surfaceUuid: fullSurface.surfaceUuid,
artworkUrl: 'https://example.com/design.png',
}],
})
}Prefer to create in the background? Pass isAsync: true and create() resolves
with a Job you await with waitForReady:
const job = await client.photoMockups.create({
sourceUrl: 'https://example.com/product.jpg',
isAsync: true,
})
const mockup = await client.photoMockups.waitForReady(job, { intervalMs: 2_000 })Update all print areas on a ready mockup with up to 8 four-point quads (each
with an optional name, 0 credits). An empty array is accepted only when
the API has verified every product surface as printable; each of those is then
a render target in its own right:
const updated = await client.photoMockups.updatePrintAreas('mockup-uuid', [{
points: [[100, 100], [900, 100], [900, 900], [100, 900]],
name: 'Front',
}])
console.log(updated.printAreas)Manage the 2D-mockup catalog:
const { mockups, total } = await client.photoMockups.list({
limit: 50,
customizableOnly: true,
})
console.log(mockups[0]?.customizable)
const mockup = await client.photoMockups.get('mockup-uuid')
await client.photoMockups.delete('mockup-uuid')Remove the background from an image; returns a public transparent-PNG cutout URL
that stays available for 7 days and that you can pass straight back as render
artwork. Supply
exactly one of url or base64. Costs 25 credits per image; credits are
refunded automatically if processing fails.
const cutout = await client.images.removeBackground({
url: 'https://example.com/product-photo.jpg',
})
console.log(cutout.url) // public transparent-PNG URL
console.log(cutout.width, cutout.height)
console.log(cutout.creditsCharged) // 25
// Reuse the cutout URL across renders for 7 days
const render = await client.renders.create({
mockupId: 'mockup-uuid',
smartObjects: [{ uuid: 'so-uuid', asset: { url: cutout.url } }],
})To clean artwork inline during a render instead, set removeBackground: true
on the render asset or 2D print area. It adds 25 credits per unique artwork
to the render (the same artwork reused across several smart objects or print
areas is charged once).
// PSD render
await client.renders.create({
mockupId: 'mockup-uuid',
smartObjects: [{
uuid: 'so-uuid',
asset: { url: 'https://example.com/photo.jpg', removeBackground: true },
}],
})
// 2D render
await client.photoMockups.render({
mockupId: 'mockup-uuid',
printAreas: [{
uuid: 'print-area-uuid',
artworkUrl: 'https://example.com/photo.jpg',
removeBackground: true,
}],
})const mockup = await client.uploads.create({
psdFileUrl: 'https://example.com/mockup.psd',
psdName: 'My T-Shirt Mockup', // optional
})
console.log(mockup.uuid)
console.log(mockup.smartObjects)
console.log(mockup.thumbnails)PSD upload is FREE (0 credits). Pass isAsync: true to process in the
background -- the call returns a Job (202) you poll via client.jobs:
const job = await client.uploads.create({
psdFileUrl: 'https://example.com/mockup.psd',
isAsync: true,
})
const done = await client.jobs.waitForJob(job.jobId)
console.log(done.mockupUuid)const account = await client.account.get()
console.log(account.account.email)
console.log(account.subscription.plan) // plan slug
console.log(account.subscription.tier) // plan tier
console.log(account.subscription.billingChannel) // 'shopify' | 'stripe' | 'none'
console.log(account.usage.creditsRemaining) // 4750
console.log(account.usage.creditsLimit) // 5000 (Starter 5K)
console.log(account.usage.prepaidBalance) // 12.5
console.log(account.usage.prepaidBalanceCurrency) // 'USD'
console.log(account.apiKey.totalRequests) // 1234
console.log(account.organization?.name) // 'Acme Prints'An account is funded either by a subscription allowance or by a prepaid balance,
and the two are independent. creditsLimit is the allowance; prepaidBalance is
money the account holds and spends per render. An account paying as it goes has no
allowance, so it reports creditsLimit: 0 and creditsRemaining: 0 while being
perfectly able to pay. Show only those two and a funded customer reads as 0 / 0.
const { usage } = await client.account.get()
if (usage.creditsLimit > 0) {
console.log(`${usage.creditsRemaining} of ${usage.creditsLimit} credits left`)
}
if (usage.prepaidBalance > 0) {
console.log(`${usage.prepaidBalance.toFixed(2)} ${usage.prepaidBalanceCurrency} balance`)
}
if (usage.creditsRemaining === 0 && usage.prepaidBalance === 0) {
console.log('No credits or balance. Add a credit card.')
}Draw a progress bar from creditsLimit only. A balance is an amount, not a
fraction, so it has no denominator to be a percentage of.
Subscriptions from $0.002 per render. Without one, $0.05 per render, the same rate standalone mockup APIs charge on a paid plan. The first payment into the balance is at least $5. 2D Mockups and video are priced by what they cost to produce, not at the flat render rate. A new account gets 500 credits once and no card is required to spend them, but until a card is verified its renders are watermarked and capped at 1,024 px, it can keep 5 PSD templates, and one render runs at a time. Funding the $5 minimum lifts every one of those: the watermark and the width cap come off, the stored-template limit goes to 150, and renders run 25 at a time alongside 10 concurrent uploads. There is no separate "free plan": that account is on the pay-as-you-go tier, unfunded.
Create customization sessions for the Studio iframe (print-on-demand integrations).
const session = await client.studio.createSession({
mockupType: '2d',
sessionKind: 'customize',
mockupUuid: 'uuid',
allowedOrigin: 'https://store.example.com',
productId: 'product-123', // optional
variantId: 'variant-456', // optional
actionId: 'add-to-cart', // optional
ui: {
primaryActionLabel: 'Add to cart',
secondaryActionLabel: 'Preview',
accentColor: '#3366FF',
},
})
// Open Studio iframe:
// studio.sudomock.com/editor?session=<session.session>
console.log(session.session) // 'sess_xxx...'
console.log(session.expiresIn) // 900 (seconds)
console.log(session.messageSessionId)
console.log(session.bootstrapSecret) // keep secret; never put it in the iframe URLUse sessionKind: 'setup' to create or edit a 2D mockup with setup controls.
Use customize for a shopper working on a prepared mockup. Setup emits
studio.mockup-saved; customize emits
studio.design-submitted. The browser message is a wire payload, so its stable
fields remain snake case. Every result has mockup_uuid, render_uuid, and the
optional action_id. Treat render_uuid as the opaque confirmation handle;
the parent page does not receive editor revision state.
On your server, confirm that browser message before saving the mockup or adding anything to a cart:
const receipt = await client.studio.consumeAction(event, {
productId: 'product-123',
variantId: 'variant-456',
})The productId and variantId must exactly match the values used to create the
session. The typed receipt is bound to the session, render, API key owner, and
commerce context, and can be consumed only once.
Manage webhook endpoints (and verify inbound deliveries) so you can react to async job completion without polling.
// Create an endpoint -- the secret is returned in full on create; store it.
const endpoint = await client.webhooks.create({
url: 'https://example.com/hooks/sudomock',
eventTypes: ['render.succeeded', 'render.failed', 'video.succeeded'],
})
await client.webhooks.list()
await client.webhooks.update(endpoint.id, { enabled: false })
await client.webhooks.rotateSecret(endpoint.id) // returns the new secret
await client.webhooks.test(endpoint.id) // send a test delivery
await client.webhooks.delete(endpoint.id)
// Per-endpoint delivery log (optional status / event_type / limit filters):
await client.webhooks.listDeliveries(endpoint.id, { status: 'failed', limit: 50 })
await client.webhooks.replayDelivery(endpoint.id, deliveryId) // replay one
await client.webhooks.replayFailed(endpoint.id) // bulk replay all failed/dead
// Cross-endpoint Events feed (recent deliveries across every endpoint):
const events = await client.webhooks.listEvents({ status: 'failed', limit: 100 })Photo-mockup events are photo_mockup.ready / photo_mockup.rejected /
photo_mockup.failed and photo_mockup_render.succeeded /
photo_mockup_render.failed. Each endpoint is pinned to one spelling
(eventNaming). Pin a new endpoint yourself on create, or leave eventNaming
out and the pin follows the spelling you subscribed in: a list in these names
pins the endpoint to current, a list in the earlier 2d_mockup.* /
2d_render.* names pins it to legacy, and an empty or mixed list pins it to
legacy. An endpoint created before these names existed keeps receiving
2d_mockup.* / 2d_render.* until you re-pin it. Subscribe with either
spelling and the delivery carries the endpoint's own.
// A handler that still expects the legacy names:
await client.webhooks.create({
url: 'https://example.com/hooks/sudomock',
eventTypes: ['2d_render.succeeded'],
eventNaming: 'legacy',
})
// Move an older endpoint to the current names once its handler is ready:
await client.webhooks.update(endpoint.id, { eventNaming: 'current' })Every delivery carries TWO headers -- X-SudoMock-Signature (hex HMAC-SHA256
digest) and X-SudoMock-Timestamp (unix seconds). The signed payload is
`${timestamp}.${rawBody}`. Verify it with the exact raw request body --
re-serialized JSON will not match:
import { verifyWebhookSignature } from 'sudomock'
// Express example -- capture the raw body (e.g. express.raw())
app.post('/hooks/sudomock', (req, res) => {
const valid = verifyWebhookSignature(
req.body.toString('utf8'), // raw payload string
req.header('X-SudoMock-Signature') ?? '',
req.header('X-SudoMock-Timestamp') ?? '',
process.env.SUDOMOCK_WEBHOOK_SECRET!,
{ toleranceSeconds: 300 }, // default; rejects replays
)
if (!valid) return res.status(400).end()
// ...handle the event
res.status(204).end()
})The check is constant-time and rejects deliveries whose timestamp drifts more than the tolerance from now.
All errors extend SudoMockError and include status (HTTP code) and code (machine-readable string).
import SudoMock, {
SudoMockError,
AuthenticationError,
CreditError,
RateLimitError,
NotFoundError,
ValidationError,
TimeoutError,
JobFailedError,
ConnectionError,
} from 'sudomock'
try {
await client.renders.create({ ... })
} catch (err) {
if (err instanceof CreditError) {
console.log('Not enough credits, upgrade at https://sudomock.com/pricing')
} else if (err instanceof RateLimitError) {
console.log(`Rate limited, retry after ${err.retryAfter} seconds`)
} else if (err instanceof AuthenticationError) {
console.log('Invalid API key')
} else if (err instanceof NotFoundError) {
console.log('Mockup not found')
} else if (err instanceof TimeoutError) {
console.log('Request timed out')
} else if (err instanceof SudoMockError) {
console.log(`API error ${err.status} (${err.code}): ${err.message}`)
}
}| Error | HTTP Status | Description |
|---|---|---|
AuthenticationError |
401 | Invalid or missing API key |
CreditError |
402 | Insufficient credits |
ValidationError |
400/422 | Invalid request parameters |
NotFoundError |
404 | Resource not found |
RateLimitError |
429 | Too many requests (check .retryAfter) |
InternalError |
500+ | Server error (auto-retried) |
TimeoutError |
-- | Request timed out |
JobFailedError |
N/A | Async job failed: .jobId identifies the job |
ConnectionError |
-- | Network/DNS failure |
The SDK automatically retries on transient errors (HTTP 408, 429, 500, 502, 503, 504) with exponential backoff. Client errors (4xx except 408/429) are never retried.
// Configure retries
const client = new SudoMock('sm_xxx', {
maxRetries: 3, // default: 2
timeout: 60_000, // default: 30s (renders use 120s automatically)
})The SDK is written in TypeScript with full type definitions for all methods and responses.
import SudoMock, {
type Mockup,
type SmartObject,
type TextLayer,
type TextLayerInput,
type RenderResult,
type AccountResult,
type CreateRenderParams,
type AIRenderParams,
type RemoveBackgroundParams,
type RemoveBackgroundResult,
type Job,
type JobStatus,
type CreateVideoParams,
type WebhookEndpoint,
type WebhookDelivery,
} from 'sudomock'Note: Webhook management methods (
client.webhooks.*) authenticate with your API key, the same as every other resource.
SudoMock also offers an official Model Context Protocol (MCP) server, enabling AI assistants like Claude, Cursor, and VS Code Copilot to generate mockups directly.
- npm package: @sudomock/mcp
- Remote server:
mcp.sudomock.com(HTTP transport, no Node.js required) - Documentation: sudomock.com/docs/mcp
MIT