Render product mockups with Laravel

SudoMock turns a Photoshop template into a finished product image over HTTP, so the Http client that already ships with Laravel is enough. This page stores the key in config/services.php, uploads a template once from an Artisan command, and renders it from a route.

Hand this to your coding agent to add SudoMock to a Laravel app.

Open in Cursor

Prerequisites

A Laravel application. The Http client is part of the framework, so there is nothing to install.
An API key from API keys. Keys start with sm_ and travel in the x-api-key header. See Authentication.
A PSD with at least one smart object, reachable at a public URL. See Preparing a PSD.
The Quickstart if you want to see the same two calls without a framework around them.

Guide

Store the key and configure the client

Put the key in the environment file and read it through a config entry. The two UUIDs stay empty until the next step fills them.

SUDOMOCK_API_KEY=sm_your_api_key
SUDOMOCK_MOCKUP_UUID=
SUDOMOCK_SMART_OBJECT_UUID=

'sudomock' => [
    'key' => env('SUDOMOCK_API_KEY'),
    'mockup' => env('SUDOMOCK_MOCKUP_UUID'),
    'smart_object' => env('SUDOMOCK_SMART_OBJECT_UUID'),
],

One macro gives every call the same base URL, header and timeout:

app/Providers/AppServiceProvider.php

use Illuminate\Support\Facades\Http;

public function boot(): void
{
    Http::macro('sudomock', function () {
        return Http::baseUrl('https://api.sudomock.com')
            ->withHeaders([
                'x-api-key' => config('services.sudomock.key'),
            ])
            ->acceptJson()
            ->timeout(120);
    });
}

Read the key with config() rather than env(). Once the config is cached in production, env() answers null and every request comes back 401.

Upload a PSD once

The upload reports the layers it found, each with the UUID you address it by. An Artisan command keeps that out of the request path.

app/Console/Commands/ImportMockup.php

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Http;

class ImportMockup extends Command
{
    protected $signature = 'sudomock:import {url} {name}';

    protected $description = 'Upload a PSD and list its layers';

    public function handle(): int
    {
        $response = Http::sudomock()
            ->post('/api/v1/psd/upload', [
                'psd_file_url' => $this->argument('url'),
                'psd_name' => $this->argument('name'),
            ]);

        if ($response->failed()) {
            $this->error($response->json('message')
                ?? $response->json('detail')
                ?? 'Upload failed');

            return self::FAILURE;
        }

        $data = $response->json('data');

        $this->line('mockup: '.$data['uuid']);

        foreach ($data['smart_objects'] as $object) {
            $this->line($object['name'].': '.$object['uuid']);
        }

        return self::SUCCESS;
    }
}

php artisan sudomock:import \
  https://example.com/heavyweight-tee.psd "Heavyweight tee"

Copy the printed mockup UUID and the UUID of the smart object you want to fill into .env. A template is uploaded once and rendered as often as you like.

Render from a route

The render takes the artwork URL from the request and answers with the finished image. On Laravel 11 and newer, php artisan install:api creates routes/api.php if the application does not have one yet.

routes/api.php

use App\Http\Controllers\RenderMockupController;

Route::post('/mockups', RenderMockupController::class);

app/Http/Controllers/RenderMockupController.php

<?php

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class RenderMockupController extends Controller
{
    public function __invoke(Request $request): JsonResponse
    {
        $input = $request->validate([
            'artwork_url' => ['required', 'url'],
        ]);

        $mockup = config('services.sudomock.mockup');
        $layer = config('services.sudomock.smart_object');

        $response = Http::sudomock()
            ->post('/api/v1/renders', [
                'mockup_uuid' => $mockup,
                'smart_objects' => [[
                    'uuid' => $layer,
                    'asset' => [
                        'url' => $input['artwork_url'],
                        'fit' => 'crop',
                    ],
                ]],
                'export_options' => [
                    'image_format' => 'webp',
                    'image_size' => 1600,
                    'quality' => 90,
                ],
            ]);

        $response->throw();

        $path = $response->json(
            'data.print_files.0.export_path'
        );

        return response()->json(['image' => $path]);
    }
}

fit decides how the artwork meets the layer, and a color block on the same entry recolours it. See Fit and blend modes.

This render holds the HTTP request open until the image exists. Send is_async as true instead and the call answers at once with a job_id you read from GET /api/v1/jobs/{job_id}, or receive on a webhook. That is the shape to pair with a queued job.

Handle a failed call

Replace throw() with a branch once the route is live. $payload is the body from the previous step. Retry the statuses that are worth repeating, and leave the rest alone.

use Illuminate\Http\Client\RequestException;
use Illuminate\Support\Facades\Log;
use Throwable;

$response = Http::sudomock()
    ->retry(3, 1000, function (Throwable $e) {
        if (! $e instanceof RequestException) {
            return true;
        }

        $status = $e->response->status();

        return $status === 429 || $status >= 500;
    }, throw: false)
    ->post('/api/v1/renders', $payload);

if ($response->failed()) {
    Log::warning('sudomock render failed', [
        'status' => $response->status(),
        'error_code' => $response->json('error_code'),
        'message' => $response->json('message')
            ?? $response->json('detail'),
    ]);

    abort(502, 'The mockup could not be rendered.');
}

A 422 means the body is wrong, so repeating it repeats the failure. A 429 carries Retry-After, which you can read from $response->header('Retry-After') and sleep for exactly that long. Every code and its remedy is on Errors.

Next steps

Errors

Every error_code, and which statuses are worth retrying.

Webhooks

Let a queued render call your app back instead of polling it.

Text layers

Replace copy in the same template without a second upload.

Usage limits

The request rate and the parallel ceiling a key works inside.

Get started

Learn

Resources

Render product mockups with Laravel

Prerequisites

Guide

Next steps

Errors

Webhooks

Text layers

Usage limits

​Prerequisites

​Guide

​Next steps

Errors

Webhooks

Text layers

Usage limits

Prerequisites

Guide

Next steps