Preparing a PSD

A template you prepare once is rendered thousands of times, so the half hour you spend in Photoshop is the cheapest half hour you will spend on it. Everything below is done before the first upload.

File requirements

Requirement	Value
Format	`.psd` or `.psb`
Photoshop version	CC 2015 or newer
Contents	At least one visible smart object or one text layer
Colour mode	RGB. CMYK, Grayscale, Indexed and Lab are converted to RGB on upload. Duotone and Multichannel render in grayscale, without their spot colours.
Bit depth	8-bit or 16-bit
Size	Up to Adobe’s own PSD file size limit over the API, and 300 MB through the dashboard

Keep the file under 100 MB when you can. Flattening the layers you never address makes the upload faster and changes nothing about the render.

Smart objects

A smart object is the slot your artwork drops into. Create one for every area you want to fill.

Select the layers that will carry the design.
Right-click and choose Convert to Smart Object.
Double-click it to edit its contents. Those contents set the design area size.

Author the contents larger than you expect to need. Scaling down keeps quality, scaling up does not. Use 3000 x 3000 px or larger for anything that goes to print.

Name the layers

Layer names come back in the upload response and are the only human-readable handle your integration has.

What good names look like in the response

{
  "smart_objects": [
    {
      "uuid": "128394ee-...",
      "name": "Front Design",
      "layer_name": "Front Design"
    },
    {
      "uuid": "7c41a9f2-...",
      "name": "Sleeve Print Left",
      "layer_name": "Sleeve Print Left"
    }
  ]
}

Layer 1, Smart Object 1 and Copy of Layer parse fine and tell you nothing six months later.

Perspective and warp

Transforms on a smart object are preserved, so build the geometry in Photoshop rather than in your request body.

Transform	Use it for
Distort	Angled surfaces such as boxes and signage
Warp	Curved surfaces such as mugs and fabric folds
Rotate	Angled placement inside the scene
Scale	The size of the area relative to the canvas

Perspective Warp stays live and renders with Adobe-level fidelity, so leave it in place instead of baking it into pixels. See Smart filters.

Layer effects

Blend modes, opacity, layer masks and clipping masks render as authored. Drop Shadow, Stroke and Blend If render as authored. Glow and Bevel are currently rasterized in Photoshop before upload, and so are 3D and video layers. See PSD compatibility for the row-by-row table.

Organise the stack

Recommended structure

T-Shirt Mockup.psd
├── Adjustments
│   ├── Brightness/Contrast
│   └── Color Balance
├── Overlays
│   ├── Fabric Texture
│   └── Shadow
├── Design Areas
│   ├── Front Design  (smart object)
│   └── Back Logo     (smart object)
├── Product
│   ├── T-Shirt Body
│   ├── Collar
│   └── Sleeves
└── Background
    └── White Background

Overlays and adjustments sit above the design areas so they read across the artwork the way they do on the finished product.

Checklist

At least one visible smart object or text layer

A hidden smart object is not exposed as a slot. Make it visible before upload.

Smart objects named descriptively

The name is what your code will match on.

Smart object contents at 3000 px or larger

Print work needs the pixels.

Layers you never address flattened

Smaller file, faster upload.

Linked smart objects embedded

Layer > Smart Objects > Embed Linked gives the highest fidelity.

Saved as .psd or .psb in RGB

Other colour modes are converted on upload.

Test it before you ship it

The file is fetched server-side, so first confirm the URL answers without a session.

Check the URL the way the API will

curl -sI "https://your-storage.com/tshirt-mockup.psd"

A 200 and a file content type mean the upload can reach it. A redirect to a sign-in page or a 403 means it cannot, whatever your browser shows while you are logged in. Then upload and read back what was detected. If a layer is missing from this response, your integration cannot address it.

const response = await fetch("https://api.sudomock.com/api/v1/psd/upload", {
  method: "POST",
  headers: {
    "x-api-key": "sm_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "psd_file_url": "https://your-storage.com/tshirt-mockup.psd"
  }),
});

const data = await response.json();
console.log(data);

<?php

$payload = <<<'JSON'
{
  "psd_file_url": "https://your-storage.com/tshirt-mockup.psd"
}
JSON;

$ch = curl_init("https://api.sudomock.com/api/v1/psd/upload");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: sm_your_api_key",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

payload = {
    "psd_file_url": "https://your-storage.com/tshirt-mockup.psd"
}

response = requests.post(
    "https://api.sudomock.com/api/v1/psd/upload",
    headers={"x-api-key": "sm_your_api_key"},
    json=payload,
)

response.raise_for_status()
print(response.json())

require "net/http"
require "uri"

uri = URI("https://api.sudomock.com/api/v1/psd/upload")
request = Net::HTTP::Post.new(uri)
request["x-api-key"] = "sm_your_api_key"
request["Content-Type"] = "application/json"

request.body = <<~JSON
  {
    "psd_file_url": "https://your-storage.com/tshirt-mockup.psd"
  }
JSON

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "psd_file_url": "https://your-storage.com/tshirt-mockup.psd"
}`)

	req, err := http.NewRequest("POST", "https://api.sudomock.com/api/v1/psd/upload", bytes.NewBuffer(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("x-api-key", "sm_your_api_key")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String payload = """
{
  "psd_file_url": "https://your-storage.com/tshirt-mockup.psd"
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sudomock.com/api/v1/psd/upload"))
    .header("x-api-key", "sm_your_api_key")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

using System.Net.Http;
using System.Text;

var payload = """
{
  "psd_file_url": "https://your-storage.com/tshirt-mockup.psd"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sudomock.com/api/v1/psd/upload");
request.Headers.Add("x-api-key", "sm_your_api_key");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var client = new HttpClient();
var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

curl -X POST "https://api.sudomock.com/api/v1/psd/upload" \
  -H "x-api-key: sm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "psd_file_url": "https://your-storage.com/tshirt-mockup.psd"
  }'

Print every slot the upload found

import requests

PSD_URL = "https://your-storage.com/tshirt-mockup.psd"

data = requests.post(
    "https://api.sudomock.com/api/v1/psd/upload",
    headers={"x-api-key": "sm_your_api_key"},
    json={"psd_file_url": PSD_URL},
).json()["data"]

for slot in data["smart_objects"]:
    print(
        "smart object",
        slot["name"],
        slot["uuid"],
        slot["size"],
    )
for layer in data["text_layers"]:
    print(
        "text layer",
        layer["name"],
        layer["uuid"],
        layer["font_available"],
    )

Then render once at full size and inspect the result before the template goes into production.

Upload a PSD

The upload contract and what every field of the response means.

Smart objects

How a design area is described and addressed.

Overview

PSD mockups

Photo mockups

Text and fonts

Integrations

Reference

Advanced

Changes

File requirements

Smart objects

Name the layers

Perspective and warp

Layer effects

Organise the stack

Checklist

Test it before you ship it

Upload a PSD

Smart objects

​File requirements

​Smart objects

​Name the layers

​Perspective and warp

​Layer effects

​Organise the stack

​Checklist

​Test it before you ship it

Upload a PSD

Smart objects

File requirements

Smart objects

Name the layers

Perspective and warp

Layer effects

Organise the stack

Checklist

Test it before you ship it