Upload a PSD

Uploading registers a Photoshop file as a reusable template. You do it once per template, and every render afterwards refers to it by UUID.

The call

Send a public URL. The file is fetched server-side, so it has to be reachable without a session cookie. A signed URL works.

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/mockup-template.psd",
    "psd_name": "T-Shirt Mockup Front"
  }),
});

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

<?php

$payload = <<<'JSON'
{
  "psd_file_url": "https://your-storage.com/mockup-template.psd",
  "psd_name": "T-Shirt Mockup Front"
}
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/mockup-template.psd",
    "psd_name": "T-Shirt Mockup Front"
}

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/mockup-template.psd",
    "psd_name": "T-Shirt Mockup Front"
  }
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/mockup-template.psd",
  "psd_name": "T-Shirt Mockup Front"
}`)

	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/mockup-template.psd",
  "psd_name": "T-Shirt Mockup Front"
}
""";

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/mockup-template.psd",
  "psd_name": "T-Shirt Mockup Front"
}
""";

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/mockup-template.psd",
    "psd_name": "T-Shirt Mockup Front"
  }'

Field	Required	Notes
`psd_file_url`	Yes	Public or signed URL to the file. Fetched with a 300 second timeout.
`psd_name`	No	Up to 255 characters. Derived from the filename when omitted.
`is_async`	No	`true` returns `202` with a `job_id` instead of waiting. Defaults to `false`.

What the response gives you

200 OK, trimmed

{
  "success": true,
  "data": {
    "uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
    "name": "T-Shirt Mockup Front",
    "thumbnail": "https://cdn.sudomock.com/thumbnails/c315f78f_720.webp",
    "width": 2000,
    "height": 3000,
    "smart_objects": [
      {
        "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
        "name": "Design Area",
        "layer_name": "Smart Object 1",
        "size": { "width": 3000, "height": 3413 },
        "position": {
          "x": 450,
          "y": 380,
          "width": 1200,
          "height": 1400
        },
        "quad": null,
        "blend_mode": "normal"
      }
    ],
    "text_layers": [
      {
        "uuid": "b7f2c1a0-9e34-4d21-8f0a-1c2b3d4e5f60",
        "name": "Headline",
        "text_content": "YOUR BRAND",
        "font_postscript_name": "Poppins-Bold",
        "font_size": 96,
        "color": "#1A1A1A",
        "font_available": true,
        "is_editable": true
      }
    ],
    "group_layers": [],
    "thumbnails": [
      {
        "width": 720,
        "url": "https://cdn.sudomock.com/thumbnails/c315f78f_720.webp"
      },
      {
        "width": 480,
        "url": "https://cdn.sudomock.com/thumbnails/c315f78f_480.webp"
      },
      {
        "width": 240,
        "url": "https://cdn.sudomock.com/thumbnails/c315f78f_240.webp"
      }
    ]
  },
  "message": ""
}

This one response carries every UUID a render needs, so there is no discovery call between upload and render. Store data.uuid as the template and the child UUIDs as its slots.

Keep the slots you will address

const { data } = await upload();

const template = {
  mockupUuid: data.uuid,
  slots: Object.fromEntries(
    data.smart_objects.map((s) => [s.name, s.uuid]),
  ),
  textSlots: Object.fromEntries(
    data.text_layers.map((t) => [t.name, t.uuid]),
  ),
};

// { "Front Design": "128394ee-...", "Back Logo": "7c41a9f2-..." }

Size against position

Two shapes on a smart object look similar and mean different things.

Field	Meaning	Use it for
`size`	The design area’s own dimensions	Authoring artwork at the right resolution
`position.x`, `position.y`	Where the area sits on the canvas	Drawing a preview overlay in a browser
`position.width`, `position.height`	Displayed size after transforms	The same preview overlay
`quad`	Four corner points of the displayed area. Included on Scale plans, `null` on lower plans.	Keeping a client-side preview aligned with the render
`blend_mode`	The layer’s authored blend mode	Deciding how a colour overlay will read

Design at size. The render scales the artwork into position for you, so those numbers never go into a render body.

Uploading in the background

A large PSD takes a while to parse. Send "is_async": true and you get a job back immediately.

202 Accepted

{
  "job_id": "5ef2a1c4-77d1-4c6a-9d33-2f8b6a0e4c10",
  "kind": "upload",
  "status": "queued",
  "status_url": "/api/v1/jobs/5ef2a1c4-77d1-4c6a-9d33-2f8b6a0e4c10"
}

Poll the job

const response = await fetch("https://api.sudomock.com/api/v1/jobs/5ef2a1c4-77d1-4c6a-9d33-2f8b6a0e4c10", {
  method: "GET",
  headers: { "x-api-key": "sm_your_api_key" },
});

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

<?php

$ch = curl_init("https://api.sudomock.com/api/v1/jobs/5ef2a1c4-77d1-4c6a-9d33-2f8b6a0e4c10");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: sm_your_api_key",
]);

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

echo $response;

import requests

response = requests.get(
    "https://api.sudomock.com/api/v1/jobs/5ef2a1c4-77d1-4c6a-9d33-2f8b6a0e4c10",
    headers={"x-api-key": "sm_your_api_key"},
)

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

require "net/http"
require "uri"

uri = URI("https://api.sudomock.com/api/v1/jobs/5ef2a1c4-77d1-4c6a-9d33-2f8b6a0e4c10")
request = Net::HTTP::Get.new(uri)
request["x-api-key"] = "sm_your_api_key"

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

puts response.body

package main

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

func main() {
	req, err := http.NewRequest("GET", "https://api.sudomock.com/api/v1/jobs/5ef2a1c4-77d1-4c6a-9d33-2f8b6a0e4c10", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("x-api-key", "sm_your_api_key")

	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;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sudomock.com/api/v1/jobs/5ef2a1c4-77d1-4c6a-9d33-2f8b6a0e4c10"))
    .header("x-api-key", "sm_your_api_key")
    .GET()
    .build();

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

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

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

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.sudomock.com/api/v1/jobs/5ef2a1c4-77d1-4c6a-9d33-2f8b6a0e4c10");
request.Headers.Add("x-api-key", "sm_your_api_key");

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

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

curl -X GET "https://api.sudomock.com/api/v1/jobs/5ef2a1c4-77d1-4c6a-9d33-2f8b6a0e4c10" \
  -H "x-api-key: sm_your_api_key"

On success the job carries mockup_uuid. Configure a webhook endpoint and the upload.succeeded event arrives instead, with no polling. Send an Idempotency-Key header so a retried upload does not register the template twice.

Practical notes

Upload once per template, not once per render. Re-uploading the same file produces a second template with its own UUIDs and spends the time again. Uploads that contain hidden smart objects come back flagged, because a hidden smart object is not exposed as a slot. Make it visible in Photoshop and upload again. See Hidden layers. Upload failures return error_code, message and detail. A file that cannot be fetched, a file that is not a PSD, and a file with no addressable layer each have their own code. They are listed in Errors.

Smart objects

What each field on a design area describes.

Render a PSD

Take those UUIDs and produce an image.

Overview

PSD mockups

Photo mockups

Text and fonts

Integrations

Reference

Advanced

Changes

The call

What the response gives you

Size against position

Uploading in the background

Practical notes

Smart objects

Render a PSD

​The call

​What the response gives you

​Size against position

​Uploading in the background

​Practical notes

Smart objects

Render a PSD

The call

What the response gives you

Size against position

Uploading in the background

Practical notes