Photo mockups

A photo mockup turns one product photograph into a template you render onto. You prepare it once, then send any artwork at it for as long as you keep it, the same way a PSD template works, without owning a layered file.

The two steps

Creating a mockup and rendering onto it are separate calls. Setup happens once per photograph; rendering happens once per design. Create the mockup

const response = await fetch("https://api.sudomock.com/api/v1/photo-mockups", {
  method: "POST",
  headers: {
    "x-api-key": "sm_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "source_url": "https://example.com/classic-tee-front.jpg",
    "name": "Classic tee, front"
  }),
});

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

<?php

$payload = <<<'JSON'
{
  "source_url": "https://example.com/classic-tee-front.jpg",
  "name": "Classic tee, front"
}
JSON;

$ch = curl_init("https://api.sudomock.com/api/v1/photo-mockups");
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 = {
    "source_url": "https://example.com/classic-tee-front.jpg",
    "name": "Classic tee, front"
}

response = requests.post(
    "https://api.sudomock.com/api/v1/photo-mockups",
    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/photo-mockups")
request = Net::HTTP::Post.new(uri)
request["x-api-key"] = "sm_your_api_key"
request["Content-Type"] = "application/json"

request.body = <<~JSON
  {
    "source_url": "https://example.com/classic-tee-front.jpg",
    "name": "Classic tee, 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(`{
  "source_url": "https://example.com/classic-tee-front.jpg",
  "name": "Classic tee, front"
}`)

	req, err := http.NewRequest("POST", "https://api.sudomock.com/api/v1/photo-mockups", 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 = """
{
  "source_url": "https://example.com/classic-tee-front.jpg",
  "name": "Classic tee, front"
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sudomock.com/api/v1/photo-mockups"))
    .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 = """
{
  "source_url": "https://example.com/classic-tee-front.jpg",
  "name": "Classic tee, front"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sudomock.com/api/v1/photo-mockups");
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/photo-mockups" \
  -H "x-api-key: sm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/classic-tee-front.jpg",
    "name": "Classic tee, front"
  }'

Send exactly one image source: source_url or source_base64. The call is synchronous by default and returns the finished mockup, so there is nothing to poll before you render.

201 Created

{
  "data": {
    "mockup_id": "9b0a74cd-0ebb-4748-a748-976fec8cc000",
    "name": "Classic tee, front",
    "status": "ready",
    "source_width": 2000,
    "source_height": 2400,
    "quads": [
      {
        "print_area_id": "223e4567-e89b-12d3-a456-426614174001",
        "points": [
          [420, 560], [1580, 560], [1600, 1840], [400, 1840]
        ],
        "sort_order": 0
      }
    ],
    "surfaces": [
      {
        "surface_uuid": "323e4567-e89b-12d3-a456-426614174002",
        "bbox": {
          "x": 300,
          "y": 380,
          "width": 1400,
          "height": 1720
        }
      }
    ]
  },
  "success": true
}

Keep three values: data.mockup_id for the render path, and a target id from either data.quads or data.surfaces. The two lists are render targets you choose between: a quad is a bounded zone drawn on the product, a surface is the whole product. A product keeps its surface entry after you draw zones on it, so a chest logo and an all over print are two entries on the same photograph. See Print areas and surfaces. Render onto it

const response = await fetch("https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/render", {
  method: "POST",
  headers: {
    "x-api-key": "sm_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "print_areas": [
      {
        "uuid": "223e4567-e89b-12d3-a456-426614174001",
        "artwork_url": "https://example.com/design.png",
        "placement": {
          "position": "center",
          "fit": "fit"
        }
      }
    ],
    "export_options": {
      "image_format": "webp",
      "image_size": 1920
    }
  }),
});

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

<?php

$payload = <<<'JSON'
{
  "print_areas": [
    {
      "uuid": "223e4567-e89b-12d3-a456-426614174001",
      "artwork_url": "https://example.com/design.png",
      "placement": {
        "position": "center",
        "fit": "fit"
      }
    }
  ],
  "export_options": {
    "image_format": "webp",
    "image_size": 1920
  }
}
JSON;

$ch = curl_init("https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/render");
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 = {
    "print_areas": [
        {
            "uuid": "223e4567-e89b-12d3-a456-426614174001",
            "artwork_url": "https://example.com/design.png",
            "placement": {
                "position": "center",
                "fit": "fit"
            }
        }
    ],
    "export_options": {
        "image_format": "webp",
        "image_size": 1920
    }
}

response = requests.post(
    "https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/render",
    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/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/render")
request = Net::HTTP::Post.new(uri)
request["x-api-key"] = "sm_your_api_key"
request["Content-Type"] = "application/json"

request.body = <<~JSON
  {
    "print_areas": [
      {
        "uuid": "223e4567-e89b-12d3-a456-426614174001",
        "artwork_url": "https://example.com/design.png",
        "placement": {
          "position": "center",
          "fit": "fit"
        }
      }
    ],
    "export_options": {
      "image_format": "webp",
      "image_size": 1920
    }
  }
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(`{
  "print_areas": [
    {
      "uuid": "223e4567-e89b-12d3-a456-426614174001",
      "artwork_url": "https://example.com/design.png",
      "placement": {
        "position": "center",
        "fit": "fit"
      }
    }
  ],
  "export_options": {
    "image_format": "webp",
    "image_size": 1920
  }
}`)

	req, err := http.NewRequest("POST", "https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/render", 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 = """
{
  "print_areas": [
    {
      "uuid": "223e4567-e89b-12d3-a456-426614174001",
      "artwork_url": "https://example.com/design.png",
      "placement": {
        "position": "center",
        "fit": "fit"
      }
    }
  ],
  "export_options": {
    "image_format": "webp",
    "image_size": 1920
  }
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/render"))
    .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 = """
{
  "print_areas": [
    {
      "uuid": "223e4567-e89b-12d3-a456-426614174001",
      "artwork_url": "https://example.com/design.png",
      "placement": {
        "position": "center",
        "fit": "fit"
      }
    }
  ],
  "export_options": {
    "image_format": "webp",
    "image_size": 1920
  }
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/render");
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/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/render" \
  -H "x-api-key: sm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "print_areas": [
      {
        "uuid": "223e4567-e89b-12d3-a456-426614174001",
        "artwork_url": "https://example.com/design.png",
        "placement": {
          "position": "center",
          "fit": "fit"
        }
      }
    ],
    "export_options": {
      "image_format": "webp",
      "image_size": 1920
    }
  }'

The finished image is at data.print_files[0].export_path.

200 OK

{
  "data": {
    "render_uuid": "9adcc828-1f4e-4a2b-9c3d-2e6f8b0a1d77",
    "print_files": [
      {
        "export_path": "https://cdn.sudomock.com/renders/2d/render.webp",
        "duration_ms": 1180,
        "export_format": "webp"
      }
    ]
  },
  "success": true
}

From here, swap artwork_url and send the call again. Every field of the render body is covered in Render artwork.

Run it in the background

Both calls accept is_async: true. You get a job instead of a result, which is what you want when you create or render in batches and do not want to hold connections open.

202 Accepted

{
  "job_id": "b7f2c1a0-9e34-4d21-8f0a-1c2b3d4e5f60",
  "kind": "photo_mockup_create",
  "status": "queued",
  "status_url": "/api/v1/jobs/b7f2c1a0-9e34-4d21-8f0a-1c2b3d4e5f60"
}

Poll status_url until the job reports succeeded, or subscribe to a webhook and skip polling. A finished create job carries the new mockup id in mockup_uuid; a finished render job puts the image in result_url. The full poll contract is in the job status reference.

Which events fire

Asynchronous work reports through five events. Subscribe on Webhooks.

Event	Meaning
`photo_mockup.ready`	The mockup was created and its targets are ready to render.
`photo_mockup.rejected`	The photograph could not be used. The payload carries a `reason`, and the credits are returned.
`photo_mockup.failed`	The create job failed unexpectedly. The credits are returned.
`photo_mockup_render.succeeded`	An asynchronous render finished and `result_url` is ready.
`photo_mockup_render.failed`	An asynchronous render failed.

A delivery can arrive more than once. Match on job_id plus the event name so a repeat is a safe no operation.

What a mockup costs you

Creating a mockup is charged once, and each render is charged per image, so the cost of a design set follows the number of designs rather than the number of photographs. A rejected or failed create returns its credits automatically. The current credit weights are on pricing. On a funded account renders come back unwatermarked at the width you asked for. While the account is on trial credits, renders carry a watermark and a reduced output width.

Print areas and surfaces

Where artwork can land, and how to move it.

Render artwork

Placement, adjustments and export options, field by field.

Create endpoint

The create contract with examples in cURL, Python and JavaScript.

Legacy paths

What the older 2D paths map to.

Overview

PSD mockups

Text and fonts

Integrations

Reference

Advanced

Changes

Photo mockups

The two steps

Run it in the background

Which events fire

What a mockup costs you

Next

Print areas and surfaces

Render artwork

Create endpoint

Legacy paths

​The two steps

​Run it in the background

​Which events fire

​What a mockup costs you

​Next

Print areas and surfaces

Render artwork

Create endpoint

Legacy paths

The two steps

Run it in the background

Which events fire

What a mockup costs you

Next