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,
)

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

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},
    },
    "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