POST

Upload PSD

Upload your Photoshop mockup template for processing. We extract smart objects, generate thumbnails, and prepare your template for rendering.

POST/api/v1/psd/upload

PSD File Requirements

File must be accessible via public URL (or signed URL)
Maximum file size: 300MB
Maximum dimensions: 10,000 x 10,000 pixels
Must contain at least one smart object layer
Supported formats: PSD and PSB (Large Document Format)
Download timeout: 120 seconds

Request

Headers

x-api-keystringRequired

Your SudoMock API key starting with sm_

Content-TypestringRequired

Must be application/json

Request Body

psd_file_urlstringRequired

URL to the PSD file. Must be publicly accessible or a signed URL. Cannot be empty (min_length: 1). The file is downloaded server-side with a 120-second timeout.

psd_namestring

Human-readable name for the mockup template (max 255 characters). Auto-generated from the URL filename if not provided.

Request Body Example

1{
2  "psd_file_url": "https://your-storage.com/mockup-template.psd",
3  "psd_name": "T-Shirt Mockup Front"
4}

Code Examples

Upload PSD

bash

1curl -X POST "https://api.sudomock.com/api/v1/psd/upload" \
2  -H "Content-Type: application/json" \
3  -H "x-api-key: sm_your_api_key" \
4  -d '{
5    "psd_file_url": "https://your-storage.com/mockup.psd",
6    "psd_name": "My Mockup Template"
7  }'

Response

Success Response

200OK

Response 200 OK

1{
2  "success": true,
3  "data": {
4    "uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
5    "name": "T-Shirt Mockup Front",
6    "thumbnail": "https://cdn.sudomock.com/thumbnails/c315f78f_720.webp",
7    "width": 2000,
8    "height": 3000,
9    "smart_objects": [
10      {
11        "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
12        "name": "Design Area",
13        "layer_name": "Smart Object 1",
14        "size": { "width": 3000, "height": 3413 },
15        "position": { "x": 450, "y": 380, "width": 1200, "height": 1400 },
16        "quad": null,
17        "blend_mode": "normal",
18        "print_area_presets": [
19          {
20            "uuid": "preset-001",
21            "name": "Default",
22            "thumbnails": [],
23            "size": { "width": 3000, "height": 3413 },
24            "position": { "x": 0, "y": 0, "width": 3000, "height": 3413 }
25          }
26        ]
27      }
28    ],
29    "text_layers": [],
30    "collections": [],
31    "thumbnails": [
32      { "width": 720, "url": "https://cdn.sudomock.com/thumbnails/c315f78f_720.webp" },
33      { "width": 480, "url": "https://cdn.sudomock.com/thumbnails/c315f78f_480.webp" },
34      { "width": 240, "url": "https://cdn.sudomock.com/thumbnails/c315f78f_240.webp" }
35    ]
36  },
37  "message": ""
38}

Response Fields

successbooleanRequired

Whether the upload was successful. Always true for 200 responses.

messagestring

Optional message about the operation. Empty string on success.

data.uuidstringRequired

Unique identifier for the mockup. Use this to render variations.

data.namestringRequired

Name of the mockup template.

data.thumbnailstring

URL to the main mockup preview image (720px width). Empty string if thumbnail generation failed.

data.widthinteger

Original PSD canvas width in pixels.

data.heightinteger

Original PSD canvas height in pixels.

data.smart_objectsarrayRequired

List of editable smart object layers found in the PSD.

data.smart_objects[].uuidstringRequired

UUID of the smart object. Use this when rendering.

data.smart_objects[].namestringRequired

Display name of the smart object.

data.smart_objects[].layer_namestring

Original PSD layer name. May differ from name.

data.smart_objects[].sizeobjectRequired

Original embedded content dimensions of the smart object ({width, height} in pixels). Upload your artwork at this resolution for best quality.

data.smart_objects[].positionobjectRequired

Bounding box of the smart object on the mockup canvas ({x, y, width, height} in pixels). Use for client-side preview overlays.

data.smart_objects[].print_area_presetsarrayRequired

Print area preset configurations. Always includes a 'Default' preset matching the full smart object area. Each preset has uuid, name, thumbnails, size, and position.

data.smart_objects[].quadarray | null

Four [x, y] coordinate pairs (floats) representing the perspective-transformed corners of the smart object. Only available on Scale tier plans; null on Free, Starter, and Pro plans.

data.smart_objects[].blend_modestring

Layer blend mode (e.g., normal, multiply). Useful for understanding how the design will composite.

data.text_layersarray

Reserved for future use. Currently always an empty array.

data.collectionsarray

Reserved for future use. Currently always an empty array.

data.thumbnailsarray

Mockup preview thumbnails at multiple sizes. Each entry has width (720, 480, or 240) and url fields.

Understanding Smart Object Data

Each smart object returns detailed metadata for seamless integration. The key distinction is between size and position:

Field	Meaning	Usage
`size.width/height`	Original embedded content dimensions	Design canvas size - upload assets at this resolution
`position.x/y`	Top-left coordinates on mockup canvas	Client-side canvas preview overlays
`position.width/height`	Display dimensions after transforms	Drawing design on thumbnail images in browser
`quad`	4-point corner coordinates (Scale tier only, null otherwise)	Canvas rendering, perspective transforms
`blend_mode`	Layer blending mode	Color overlays, special effects

size vs position

size = Upload your design at this resolution, use these coordinates in render API requests.
position = Use for drawing client-side previews on thumbnail images in browser. Not needed for API calls.

Error Responses

PSD processing errors (400, 500) return a structured body with error_code, message, detail, details, and success fields.

400Bad Request

Returned when the PSD cannot be downloaded, is too large (over 300MB), fails to parse, contains no smart objects, or uses unsupported features.

json

1// PSD download failed
2{
3  "error_code": "PSD_DOWNLOAD_FAILED",
4  "message": "Failed to download PSD file",
5  "detail": "Failed to download PSD file",
6  "details": {
7    "url": "https://example.com/broken-link.psd",
8    "reason": "HTTP 404",
9    "suggestion": "Check if the URL is accessible and the file exists"
10  },
11  "success": false
12}
13
14// PSD too large (300MB limit)
15{
16  "error_code": "PSD_TOO_LARGE",
17  "message": "PSD file too large (352.1MB)",
18  "detail": "PSD file too large (352.1MB)",
19  "details": {
20    "file_size_mb": 352.1,
21    "max_size_mb": 300.0,
22    "suggestion": "Reduce file size to under 300.0MB or optimize layers"
23  },
24  "success": false
25}
26
27// No smart objects
28{
29  "error_code": "NO_SMART_OBJECTS",
30  "message": "PSD file contains no smart objects",
31  "detail": "PSD file contains no smart objects",
32  "details": {
33    "total_layers": 12,
34    "suggestion": "Add at least one Smart Object layer in Photoshop (Layer > Smart Objects > Convert to Smart Object)"
35  },
36  "success": false
37}

401Unauthorized

Returned when your API key is missing, malformed, or revoked.

json

1{
2  "detail": "Not authenticated",
3  "success": false
4}

402Payment Required

Returned when you have no remaining credits for PSD uploads.

json

1{
2  "error": "credits_exhausted",
3  "message": "You've run out of credits for this billing period.",
4  "actions": [
5    { "label": "Enable Pay-As-You-Go", "url": "https://sudomock.com/dashboard/billing?action=enable-payg" },
6    { "label": "Upgrade Plan", "url": "https://sudomock.com/pricing" }
7  ],
8  "credits_reset_at": "2026-04-01T00:00:00Z"
9}

422Validation Error

Returned by FastAPI when request body validation fails (e.g., missing required field, empty psd_file_url, or psd_name over 255 characters).

json

1{
2  "detail": "Validation error",
3  "errors": [
4    {"field": "body -> psd_file_url", "message": "Missing required field: body -> psd_file_url"}
5  ],
6  "success": false
7}

429Too Many Requests

Returned when you exceed the API rate limit or concurrent upload limit.

json

1{
2  "detail": "Rate limit exceeded. Please slow down and try again.",
3  "error": {
4    "type": "rate_limit_exceeded",
5    "code": "RATE_LIMIT_EXCEEDED",
6    "limit": 1000,
7    "remaining": 0,
8    "reset_seconds": 30,
9    "retry_after": 30,
10    "resource": "api"
11  }
12}

500Internal Server Error

Returned when an unexpected error occurs during PSD processing (e.g., smart object extraction failure, storage error).

json

1{
2  "error_code": "INTERNAL_ERROR",
3  "message": "An unexpected error occurred while processing the PSD file",
4  "detail": "An unexpected error occurred while processing the PSD file",
5  "details": {
6    "suggestion": "Please try again. If the problem persists, contact support."
7  },
8  "success": false
9}

Try It Live

POST/api/v1/psd/upload

Upload a PSD file and extract smart objects.

API Key

Get your API key from the Dashboard

Request Body

Best Practices

PSD Preparation Tips

Name your smart object layers descriptively (e.g., "Front Design", "Back Logo")
Use high-resolution smart objects (3000x3000px or higher)
Flatten non-editable layers to reduce file size
Keep smart objects in separate layer groups if possible

Common Issues

PSD_DOWNLOAD_FAILED: Ensure your URL is publicly accessible or use a signed URL. Downloads time out after 120 seconds.
NO_SMART_OBJECTS: Convert your design layers to smart objects in Photoshop (Layer > Smart Objects > Convert to Smart Object).
PSD_TOO_LARGE: Files over 300MB are rejected. Flatten non-editable layers or reduce image resolution to decrease file size.
UNSUPPORTED_SMART_OBJECT_FORMAT: Smart objects containing AI, PDF, EPS, or SVG files are not supported. Use raster formats (PNG, JPG, TIFF, PSD/PSB).

Next: Learn how to render mockups with your uploaded templateRender Mockup