SudoMock Python SDK

Official Python client for the SudoMock Mockup Generator API.

Generate photorealistic product mockups from PSD templates or 2D mockups -- all from your Python code.

Installation

pip install sudomock

Quick Start

from sudomock import SudoMock

# 1. Create a client (or set SUDOMOCK_API_KEY env var)
client = SudoMock(api_key="sm_your_api_key")

# 2. List your mockup templates
mockups = client.mockups.list(limit=10)
for m in mockups.mockups:
    print(f"{m.name} ({m.uuid})")

# 3. Render a mockup with your artwork
render = client.renders.create(
    mockup_uuid=mockups.mockups[0].uuid,
    smart_objects=[{
        "uuid": mockups.mockups[0].smart_objects[0].uuid,
        "asset": {"url": "https://example.com/your-design.png"},
    }],
)
print(render.url)  # https://cdn.sudomock.com/renders/.../render.webp

Batch text personalization

Use an editable text layer from the mockup response to create personalized outputs. smart_objects is optional for text-only renders, and fit defaults to "overflow".

mockup = client.mockups.get("mockup-uuid")
name_layer = next(layer for layer in mockup.text_layers if layer.name == "Customer Name")
if not name_layer.is_editable:
    raise ValueError("Customer Name is not editable")

renders = [
    client.renders.create(
        mockup_uuid=mockup.uuid,
        text_layers=[{
            "uuid": name_layer.uuid,
            "text": name,
            "font": "Montserrat-Bold",
            "color": "#FFFFFF",
            "fit": "overflow",
        }],
    )
    for name in ["Aylin", "Deniz", "Mert"]
]

for render in renders:
    print(render.url)
    for warning in render.warnings:
        print(warning.code, warning.message)

Async Usage

import asyncio
from sudomock import AsyncSudoMock

async def main():
    async with AsyncSudoMock(api_key="sm_your_api_key") as client:
        mockups = await client.mockups.list()
        render = await client.renders.create(
            mockup_uuid=mockups.mockups[0].uuid,
            smart_objects=[{
                "uuid": mockups.mockups[0].smart_objects[0].uuid,
                "asset": {"url": "https://example.com/design.png"},
            }],
        )
        print(render.url)

asyncio.run(main())

2D mockups via API

Create a 2D mockup from a product image, wait until its print areas are ready, then render your artwork. Creation costs 25 credits and rendering costs 5 credits. Unsuccessful creations are refunded automatically.

from sudomock import SudoMock

client = SudoMock(api_key="sm_your_api_key")

# Create the 2D mockup (synchronous by default -- returns the finished mockup)
mockup = client.ai.create(
    source_url="https://example.com/product.jpg",
    name="Product Front",
    idempotency_key="product-front-001",
)

render = client.ai.render(
    mockup_uuid=mockup.mockup_id,
    print_areas=[{
        "uuid": mockup.quads[0].print_area_id,
        "artwork_url": "https://example.com/your-design.png",
    }],
)
print(render.url)

# Async variant: submit to the server queue and poll (returns a JobAccepted)
job = client.ai.render(
    mockup_uuid=mockup.mockup_id,
    print_areas=[{
        "uuid": mockup.quads[0].print_area_id,
        "artwork_url": "https://example.com/your-design.png",
    }],
    is_async=True,
)
result = client.jobs.wait(job.job_id)   # terminal Job carries result_url
if result.succeeded:
    print(result.url)

Async Rendering (Server-Side Queue)

Submit long-running renders to the server-side queue and poll for the result. This is independent of AsyncSudoMock -- is_async controls server queueing, while AsyncSudoMock only controls how your process performs HTTP I/O. Either client can submit async jobs.

from sudomock import SudoMock

client = SudoMock(api_key="sm_your_api_key")

# Submit -> returns a JobAccepted (HTTP 202), does not block on the render
job = client.renders.create(
    mockup_uuid="...",
    smart_objects=[{"uuid": "...", "asset": {"url": "https://example.com/d.png"}}],
    is_async=True,
)
print(job.job_id, job.status_url)

# Poll until terminal (succeeded / failed)
result = client.jobs.wait(job.job_id)        # or client.jobs.get(uuid) once
if result.succeeded:
    print(result.url)        # result_url
else:
    print("failed:", result.error)

Video Rendering

Animate a mockup into an AI video. Video renders are always async (return a JobAccepted). The first video render on a free plan is granted once for the account's lifetime. duration_seconds must be a value allowed by the chosen model (otherwise the API returns 422).

job = client.renders.create_video(
    mockup_uuid="...",
    smart_objects=[{"uuid": "...", "asset": {"url": "https://example.com/d.png"}}],
    duration_seconds=5,
    audio=False,
    motion="ambient",               # optional; "ambient" (default) or "showcase"
    advanced_model="veo-3.1-fast",  # optional; otherwise auto-selected by tier
)
video = client.jobs.wait(job.job_id)
print(video.url)

# Raw-image mode: animate a public image URL directly (no mockup render step)
job = client.renders.create_video(
    image_url="https://example.com/product.jpg",
    duration_seconds=5,
)

Background Removal

Remove the background from an image; returns a signed transparent-PNG cutout URL valid for 7 days that you can hand straight back to a render as artwork. The cutout itself remains retained for your account. Supply exactly one of url or base64. Costs 25 credits per image; credits are refunded automatically if processing fails.

cutout = client.images.remove_background(url="https://example.com/product-photo.jpg")

print(cutout.url)              # signed cutout URL, valid for 7 days
print(cutout.width, cutout.height)
print(cutout.credits_charged)  # 25

# Reuse the URL in renders during its 7-day validity window
render = client.renders.create(
    mockup_uuid="mockup-uuid",
    smart_objects=[{"uuid": "so-uuid", "asset": {"url": cutout.url}}],
)

To clean artwork inline during a render instead, set remove_background 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
client.renders.create(
    mockup_uuid="mockup-uuid",
    smart_objects=[{
        "uuid": "so-uuid",
        "asset": {"url": "https://example.com/photo.jpg", "remove_background": True},
    }],
)

# 2D render
client.ai.render(
    mockup_uuid="mockup-uuid",
    print_areas=[{
        "uuid": "print-area-uuid",
        "artwork_url": "https://example.com/photo.jpg",
        "remove_background": True,
    }],
)

PSD Upload

Upload a PSD by URL and parse it into a mockup template. PSD uploads are free (zero credits) and support is_async.

mockup = client.psd.upload(url="https://example.com/template.psd", name="My PSD")
print(mockup.uuid)

# Async variant:
job = client.psd.upload(url="https://example.com/template.psd", is_async=True)
mockup = client.jobs.wait(job.job_id)

Webhooks

Manage outbound webhook endpoints (authenticated with your x-api-key) and verify inbound HMAC-signed deliveries.

# Register an endpoint
ep = client.webhook_endpoints.create(
    url="https://your-app.com/webhooks/sudomock",
    events=["render.succeeded", "render.failed"],
)
print(ep.secret)  # store this -- it signs deliveries

# List / update / rotate / test / replay
client.webhook_endpoints.list()
client.webhook_endpoints.update(ep.id, enabled=False)
client.webhook_endpoints.rotate_secret(ep.id)
client.webhook_endpoints.test(ep.id)
deliveries = client.webhook_endpoints.deliveries(ep.id)
client.webhook_endpoints.replay_delivery(ep.id, deliveries.deliveries[0].id)

# Cross-endpoint deliveries feed + bulk replay of all failed deliveries
client.webhook_endpoints.events(limit=100)
client.webhook_endpoints.replay_failed(ep.id)

Verify an inbound delivery in your handler (use the raw request body). SudoMock sends the signature and timestamp in two separate headers:

from sudomock import verify_webhook_signature
from sudomock.exceptions import WebhookVerificationError

signature = request.headers["X-SudoMock-Signature"]  # hex HMAC-SHA256 digest
timestamp = request.headers["X-SudoMock-Timestamp"]  # unix timestamp
try:
    verify_webhook_signature(secret, signature, timestamp, raw_body)
except WebhookVerificationError:
    ...  # reject: missing header / replayed / bad signature

Error Handling

from sudomock import SudoMock
from sudomock.exceptions import (
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
    NotFoundError,
    ValidationError,
    ServerError,
    SudoMockError,  # base class for all errors
)

client = SudoMock(api_key="sm_your_api_key")

try:
    render = client.renders.create(
        mockup_uuid="...",
        smart_objects=[...],
    )
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError as e:
    print(f"Out of credits. Resets at: {e.credits_reset_at}")
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after}s")
except NotFoundError:
    print("Mockup not found")
except ValidationError:
    print("Invalid request parameters")
except ServerError:
    print("Server error, will be retried automatically")
except SudoMockError as e:
    print(f"Unexpected error: {e.message} (HTTP {e.status_code}, code={e.error_code})")

Account & Credits

from sudomock import SudoMock

client = SudoMock(api_key="sm_your_api_key")
account = client.account.get()

print(f"Plan: {account.subscription.plan}")
print(f"Credits remaining: {account.usage.credits_remaining}")
print(f"Credits limit: {account.usage.credits_limit}")
print(f"Period ends: {account.subscription.current_period_end}")

Configuration

from sudomock import SudoMock

client = SudoMock(
    api_key="sm_your_api_key",           # or SUDOMOCK_API_KEY env var
    base_url="https://api.sudomock.com", # default
    timeout=30.0,                         # default request timeout (seconds)
    render_timeout=120.0,                 # render request timeout (seconds)
    max_retries=3,                        # TOTAL attempts on 429/5xx/network: initial + up to 2 retries (exponential backoff)
)

API Reference

Mockups

Bulk delete (DELETE /mockups/all) is dashboard-only (Bearer/JWT auth) and is intentionally not exposed in this api-key SDK.

Renders

Jobs

PSD

2D Mockups

Images

Account

Packages (public)

Webhook Endpoints

Export Options

export_options = {
    "image_format": "webp",  # "webp", "png", "jpg"
    "image_size": 1920,       # max dimension in pixels
    "quality": 95,            # 1-100 (for webp/jpg)
}

Smart Object Configuration

smart_objects = [{
    "uuid": "smart-object-uuid",
    "asset": {
        "url": "https://example.com/design.png",
        "fit": "fill",      # "fill" (default), "contain", "cover"
        "rotate": 0,         # degrees
        "position": {"top": 100, "left": 100},
        "size": {"width": 800, "height": 600},
        "remove_background": False,  # True isolates the subject (+25 credits per artwork)
    },
    "color": {
        "hex": "#FFFFFF",
        "blending_mode": "multiply",
    },
}]

Requirements

• Python 3.9+
• httpx for HTTP
• Pydantic v2 for response models
• tenacity for retry logic

License

MIT -- see LICENSE.

MCP Server

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

Links

• SudoMock Website
• API Documentation
• Dashboard
• MCP Server