API & Developer Guides

How to Upload a Custom PSD Template to a Mockup Generator So Your Brand's Unique Scenes Render Consistently at Scale

By Mockupanda10 min read
How to Upload a Custom PSD Template to a Mockup Generator So Your Brand's Unique Scenes Render Consistently at Scale

Every print-on-demand seller eventually hits the same wall. The built-in template library is fine for launching, but once you have a branded aesthetic, a custom lifestyle photograph, or a premium scene from a mockup marketplace, you want that specific environment to show up on every listing, not just the ones where you happened to have time to open Photoshop. The good news is that Mockupanda supports custom PSD uploads with Smart Object layers, which means your proprietary scenes can live right alongside the built-in library and render in real time with zero Photoshop involvement.

This post covers everything from PSD structure to upload mechanics to bulk rendering, so you can get your brand's unique scenes working consistently at whatever scale your catalog demands.

What Makes a PSD Template Work in a Mockup Generator

Not every PSD file is automatically ready to drop into a mockup generator. The tool needs a known hook inside the file, a specific layer it can target and replace with your artwork. Getting this right before you upload saves you from troubleshooting later.

The Smart Object Layer Requirement

The single most important requirement is that your PSD must contain a Smart Object layer named exactly Design, and that layer must be the active (selected) layer when you save the file. This is not a suggestion; it is what the renderer looks for.

A Smart Object is a special layer type in Photoshop that acts as a placeholder. When new artwork is substituted into it, the image is automatically warped, scaled, and blended to match the surrounding scene, giving you a photorealistic result without manually adjusting perspective or lighting. That is precisely why the Smart Object convention works so well for mockup rendering: the layer carries all of the transform, perspective, and blending data that makes artwork look like it belongs in the scene.

PSDs from Creative Market, Envato Elements, and other mockup marketplaces typically already follow this naming convention. If you bought a premium pack, open it in Photoshop, check the Layers panel, and confirm there is a layer called Design. If it is named something else, rename it, make sure it is selected, and save. Files up to 300 MB are supported.

How the PSD Should Be Structured

Beyond the Smart Object layer, a well-structured PSD has three logical parts. First, the Smart Object layer itself, which is where your artwork will be placed. Second, the background elements, things like the product surface, the room, the table, the wall, whatever the static scene contains. Third, any effects layers, lighting overlays, shadow layers, or clipping masks that sit above the Smart Object so they render on top of the placed artwork and give it depth.

If your effects layers are grouped incorrectly or sit below the Smart Object in the layer stack, they will not appear on top of your artwork in the final render. A quick sanity check: flatten a test version of the file with a solid-color fill in the Smart Object and confirm the shadows and lighting still appear correctly over that fill.

Actionable takeaway: Before uploading any PSD, open it, rename the Smart Object layer to Design, confirm it is the active layer, check that lighting and shadow layers sit above it in the stack, then save.

Uploading Your Custom PSD to Mockupanda

Once your PSD is structured correctly, the actual upload process is straightforward. Mockupanda lets you upload custom PSD templates directly from the editor, and your custom templates appear in the generator alongside the built-in library.

Using the Editor to Upload

In the editor, there is an option to upload a PSD or create a new template from any image. You drag and drop your PSD file into the upload area.

Once uploaded, your custom template becomes a user template in your account, distinct from built-in library templates. The API distinguishes between these two kinds of template using a source field: library templates have "source": "library" and your uploads have "source": "custom". This distinction matters when you are querying templates programmatically, because you can filter specifically for your custom scenes.

Custom Templates Versus Library Templates

It is worth understanding the relationship between library templates and custom templates, because it affects how you manage updates. A library template always renders the scene exactly as it ships from the platform. If you want to customize a library template, you add it to your own templates first, which gives you a copy with its own ID. The original library ID keeps rendering the original version, so any existing API calls or workflows that reference it are unaffected.

For a PSD you upload yourself, the template gets its own ID in your account from the moment it is created. If you edit that template later in the dashboard, the edits save onto the same ID. That means your API calls will automatically render the updated version without any changes on your end. This is a significant advantage when you are iterating on a scene: update once in the dashboard, and every downstream call picks up the new version automatically.

Actionable takeaway: After uploading, note the template ID assigned to your custom PSD. Use that ID in any API calls or Sets you configure, and remember that editing the template in the dashboard updates the render without requiring an ID change.

Rendering Custom PSD Templates in Bulk

Uploading the PSD is only half the job. The real payoff comes when you can apply a fresh design to that scene across many listings without repeating the upload or the render setup each time.

Applying One Design Across Your Custom Templates

In the editor, the bulk mockup workflow lets you upload a design once and apply it to every template you select, including your custom PSD uploads. Your custom templates appear in the generator alongside the built-in wall art and frame options. Select the ones you want, generate all mockups, and download them as a single ZIP file of high-resolution JPEGs.

For sellers who need consistent mockups across a large catalog, this approach eliminates the per-template repetition that makes manual Photoshop work so slow. The batch workflow handles the perspective, the Smart Object replacement, and the export automatically.

If you are applying one design across dozens of templates and some of those templates are your own branded PSDs, the experience is identical to working with built-in templates. Your custom scenes slot in without friction.

Using Sets to Lock In Your Custom Scene Lineup

If your brand always uses the same combination of templates for every new listing, Sets are the right tool for capturing that combination once and reusing it infinitely. A Set is a named, ordered group of templates saved in the app. It can mix built-in templates with your own custom PSD uploads. Once you have saved a Set, you can render the entire group with a single set_id via the API instead of repeating the same list of template IDs in every request.

This is especially useful when you are scaling a POD catalog past a certain number of listings and consistency becomes a business requirement rather than a nice-to-have. Define the Set once, include your custom PSD templates in it, and every new design you push through the API automatically gets rendered against your brand's specific scenes in the right order.

Actionable takeaway: Create a Set in the app that includes your custom PSD template IDs alongside any built-in templates you use. Reference that set_id in your API calls so every new design gets the same scene lineup without manual configuration.

Rendering Custom PSDs via the API

For sellers and developers who want to automate mockup generation, the Mockupanda API exposes your custom templates exactly the same way it exposes built-in ones. Once a PSD is uploaded and has an ID in your account, you can call POST /mockups/generate with that template ID and an artwork_url, and the API renders the result.

Querying Your Custom Templates

The GET /templates endpoint lists templates, and each template indicates whether it is one of yours (is_user_template) or part of the library. This is how you programmatically confirm that your uploaded PSD is registered, retrieve its ID, and verify its metadata before including it in a batch request.

The API also supports a hybrid semantic search using the q parameter, so if you have uploaded multiple custom scenes and want to find a specific one by description, you can query by keyword rather than needing to remember IDs.

Batch Mode and Multi-Frame PSDs

The API's batch mode lets you pass up to 12 template IDs in a single request using the template_ids parameter. If a template is multi-frame, such as a diptych or triptych where the scene contains two or three artwork panels, you use artwork_urls instead of a single artwork_url. Frame indices start at 0, so a three-frame template takes keys "0", "1", and "2" mapped to the respective artwork URLs.

Artwork aspect ratio matters here. Each print template expects artwork that matches the frame proportions. Artwork that does not match will be cropped or stretched to fill the frame, which is what makes a mockup look wrong. If your PSD has a specific aspect ratio built into the Smart Object, make sure the artwork you send matches it, or use the aspect-ratio filtering options the API provides to find templates that fit a given artwork dimension.

The render times are fast: simple templates finish in one to two seconds, more complex scenes in two to four seconds, and maximum resolution output at 4000px takes three to five seconds. Failed requests cost zero credits, so testing your custom template IDs in the API before wiring them into a production workflow does not carry a financial penalty.

Actionable takeaway: Use GET /templates and check is_user_template to retrieve your custom PSD's template ID, then test a single POST /mockups/generate call against it before adding it to a Set or a batch workflow. Confirm the aspect ratio expectations match your artwork before scaling up.

Maintaining Consistency Across a Growing Catalog

Consistency is the whole point of uploading a custom PSD. Once the scene is in the system and rendering correctly, the goal is to make sure every future design looks as good as the first one did.

Artwork Quality and Format Considerations

The web app accepts JPEG, PNG, GIF, and WebP files as artwork input. For designs that do not fill the entire Smart Object area, a high-resolution PNG with a transparent background gives the best result, because the transparency is preserved and the scene's background shows through naturally rather than being blocked by a white fill.

All mockups download as high-quality JPEGs. Through the API, the default output width is 2000px, with a maximum of 4000px available. If you are uploading artwork for a custom PSD that has a high-resolution Smart Object area, sending artwork that matches or exceeds the output resolution keeps the final image sharp. The platform does not apply AI upscaling or introduce distortion, so what you put in is what comes out, pixel-perfect.

Keeping Your Custom Template Updated Without Breaking Downstream Calls

One of the more practical advantages of how custom templates work is the update behavior. When you edit a custom template in the dashboard, the changes apply to the existing template ID. Any API call or Set that references that ID will automatically render the new version. You do not need to update template IDs in your code, your Sets, or your automation scripts.

This makes it safe to iterate on a scene. If you want to adjust the scene, you can edit the template in the dashboard and all existing references pick up the update. For sellers managing hundreds of listings, that kind of update propagation without manual ID management is a meaningful time saver.

Actionable takeaway: Treat your custom PSD template IDs as stable references. Build your Sets and API calls around them from day one, knowing that if you ever need to update the scene, you can do so in the dashboard without touching your integration.

Putting It All Together

Uploading a custom PSD to Mockupanda is a process with a small number of firm requirements, specifically the Design Smart Object layer naming and the layer being active on save, and a straightforward path once those are met. Your custom scenes live in your account with their own IDs, render identically to built-in templates through both the editor and the API, and can be grouped into Sets so your brand's specific scene lineup is one set_id away from rendering for any new design you produce.

The combination of a correctly structured PSD, a Set that captures your preferred template lineup, and the API's batch mode gives you a pipeline where launching a new design means one upload and one API call, not an afternoon in Photoshop. That is the kind of consistency that makes scaling a catalog from ten listings to a thousand feel manageable rather than overwhelming.