SudoMock
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
  • Must contain at least one smart object layer
  • Supported: Photoshop CC 2015 and newer

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.

psd_namestring

Human-readable name for the mockup template. Auto-generated from 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.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            "size": { "width": 3000, "height": 3413 },
23            "position": { "x": 0, "y": 0, "width": 3000, "height": 3413 }
24          }
25        ]
26      }
27    ],
28    "text_layers": [],
29    "collections": [],
30    "thumbnails": [
31      { "width": 720, "url": "https://cdn.sudomock.com/thumbnails/c315f78f_720.webp" },
32      { "width": 480, "url": "https://cdn.sudomock.com/thumbnails/c315f78f_480.webp" },
33      { "width": 240, "url": "https://cdn.sudomock.com/thumbnails/c315f78f_240.webp" }
34    ]
35  },
36  "message": ""
37}

Response Fields

uuidstringRequired

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

namestringRequired

Name of the mockup template.

thumbnailstring

URL to the mockup preview image.

widthinteger

Original PSD width in pixels.

heightinteger

Original PSD height in pixels.

smart_objectsarrayRequired

List of editable smart object layers in the PSD.

smart_objects[].uuidstringRequired

UUID of the smart object. Use this when rendering.

smart_objects[].namestringRequired

Human-readable name of the smart object.

smart_objects[].sizeobjectRequired

Original dimensions of the smart object content (width, height).

smart_objects[].positionobjectRequired

Position and size of the smart object in the mockup (x, y, width, height).

smart_objects[].quadarray

Four [x, y] coordinate pairs representing the corners of the smart object bounds. Useful for canvas rendering.

smart_objects[].blend_modestring

Layer blend mode (e.g., normal, multiply). Important for color overlays.

Understanding Smart Object Data

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

FieldMeaningUsage
size.width/heightOriginal embedded content dimensionsDesign canvas size - upload assets at this resolution
position.x/yTop-left coordinates on mockup canvasClient-side canvas preview overlays
position.width/heightDisplay dimensions after transformsDrawing design on thumbnail images in browser
quad4-point corner coordinatesCanvas rendering, perspective transforms
blend_modeLayer blending modeColor 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

400Bad Request
json
1{
2  "success": false,
3  "detail": "Invalid PSD file URL"
4}
401Unauthorized
json
1{
2  "success": false,
3  "detail": "Invalid or missing API key"
4}
422Validation Error
json
1{
2  "detail": [
3    {
4      "loc": ["body", "psd_file_url"],
5      "msg": "field required",
6      "type": "value_error.missing"
7    }
8  ]
9}

Try It Live

POST/api/v1/psd/upload

Upload a PSD file and extract smart objects.

Get your API key from the Dashboard

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

  • File not accessible: Ensure your URL is publicly accessible or use a signed URL
  • No smart objects found: Convert your design layers to smart objects in Photoshop
  • Processing timeout: Very large files (>200MB) may take longer. Consider optimizing.
Next: Learn how to render mockups with your uploaded templateRender Mockup