How to Use the Mockupanda API's Semantic Search to Find the Perfect Template Without Browsing a Library of 100+ Options

The Problem With Browsing a 100-Template Library by Hand

If you have ever tried to scale a print-on-demand catalog programmatically, you already know the bottleneck. You can automate design uploads, automate order routing, even automate pricing. But somewhere in the middle of that pipeline sits a very manual step: opening a mockup tool, scrolling through rows of templates, squinting at thumbnails, and picking the one that actually fits your artwork's proportions and your listing's aesthetic.

At small volume that is annoying. At scale, with hundreds of designs going live every month, it becomes a genuine blocker.

Mockupanda solves this with a hybrid semantic search built directly into the GET /templates endpoint of its REST API. Instead of fetching every template and filtering the results yourself, you pass a plain-language query, a few optional filters, and get back only the templates that actually match. No thumbnail grid. No manual triage. Just the right options, ready to render.

This guide covers exactly how that works, what parameters you have available, how to read the response, and how to wire it all into an automated pipeline.

Why Semantic Search Is Different From a Keyword Filter

A basic keyword filter matches on exact strings. You search for "poster" and you get templates whose names contain the word "poster." That sounds fine until you realize a template named "wall art frame" or "gallery print scene" is exactly what you needed but never surfaced.

Semantic search understands intent. The q parameter on the GET /templates endpoint uses a hybrid approach that combines traditional text matching with vector-based similarity. In practice, that means a query like "cozy bedroom wall art with natural light" can return templates that match the vibe and use case even if none of those exact words appear in a template's metadata.

For programmatic workflows, this is significant. You can derive a query automatically from a design's filename, its category tag in your product database, or even a short description your team writes at upload time, and let the API surface the best-fit templates without a human ever opening a browser.

What the Endpoint Looks Like

The base endpoint is:

GET https://www.mockupanda.com/api/v1/templates

Authentication uses a Bearer token from your Dashboard under API Keys. Every request needs that header:

Authorization: Bearer YOUR_API_KEY

The key parameters you will use for search and filtering are:

• q — your plain-language semantic query

• aspect_ratio — filter by the aspect ratio of the template's frame (e.g. 1:1, 4:5, 2:3)

• match_artwork — a boolean that filters for templates whose frame proportions match your uploaded artwork's dimensions

You can combine all three. In most automated workflows you will want to.

Writing a Semantic Query That Actually Works

The q parameter is more forgiving than a keyword search, but the quality of your query still matters. A vague query returns a broader set of templates. A specific, descriptive query narrows it to exactly what you need.

Describing the Scene, Not Just the Product

Think about how you would describe the physical setting of the mockup to a human colleague, not just the product type.

Instead of: "poster mockup"

Try: "minimalist living room poster in thin black frame"

Instead of: "square print"

Try: "square art print on white wall with soft natural light"

The more you describe the environment, the lighting style, the frame type, and the overall mood, the more the semantic layer can differentiate between templates that are technically similar product types but visually very different scenes.

For a catalog automation workflow, a practical pattern is to store a short scene description alongside each design category in your product database. When a new design gets tagged as "botanical illustration, portrait," your pipeline queries the API with something like "portrait wall art botanical light airy gallery frame" and pulls the top three results for that category automatically.

Queries for Specific Product Types

The Mockupanda template library covers more than posters and wall art. Here are example queries that work well for different product types:

For digital wall art prints: "framed art print bedroom wall neutral tones" "gallery wall set living room styled mockup" "poster on white wall minimal Scandinavian interior"

For apparel: "white t-shirt flat lay on concrete" "folded hoodie lifestyle photo studio"

For home products: "tote bag hanging natural cotton" "mug on wooden desk morning coffee"

The key habit is to describe the shot as if you are briefing a photographer: surface, lighting, setting, product orientation.

Combining the Query With Aspect Ratio Filters

Semantic search gets dramatically more useful when you pair it with the aspect_ratio filter. If your design is a 2:3 portrait print and you are searching for bedroom wall art scenes, there is no point getting back square or landscape templates in the results. Adding aspect_ratio=2:3 to the same request eliminates that noise immediately.

A full request combining both might look like this in cURL:

curl -X GET \
  "https://www.mockupanda.com/api/v1/templates?q=minimalist+bedroom+poster+frame&aspect_ratio=2:3" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response comes back with only 2:3-framed templates ranked by semantic relevance to your scene description. You pick the top result, or the top three, and pipe those template_id values directly into your /mockups/generate call.

Filtering by Artwork Dimensions With match_artwork

Aspect ratio filtering is great when you know your design's ratio in advance. But in a high-volume pipeline where designs come in from multiple contributors or in varying sizes, you might not always want to hardcode a ratio. That is where match_artwork becomes useful.

How match_artwork Works

When you pass match_artwork=true, the API filters the template list to show only templates whose frame dimensions are compatible with the artwork you have already uploaded. It uses your artwork's actual pixel dimensions to determine which templates will render cleanly without distortion or empty space.

This is particularly valuable if you are processing a queue of uploads automatically. Each design gets its own filtered template list based on its own dimensions. You never have to manually check whether a 2480x3508 px file will sit correctly inside a landscape scene.

You would typically use this after uploading an artwork file and receiving back its dimensions, then pass match_artwork=true as part of the subsequent template discovery call. The result is a list of templates where your specific artwork fits without any awkward cropping or scaling compromises.

Pairing Artwork Matching With Semantic Search

The most powerful version of this workflow combines all three parameters at once:

curl -X GET \
  "https://www.mockupanda.com/api/v1/templates?q=gallery+wall+art+natural+light&match_artwork=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

This gives you templates that:

1. Match the described scene semantically

2. Are dimensionally compatible with your specific artwork

For an automated catalog pipeline, this two-line query replaces the entire manual step of browsing templates. Your system gets back a ranked, filtered list it can act on immediately.

Actionable takeaway: In your automation scripts, always combine q with either aspect_ratio or match_artwork. Running semantic search alone returns broader results. The filters are what make the output immediately actionable.

Reading the Response and Selecting the Right Template

Knowing what to do with the API response is just as important as forming a good query. The GET /templates response returns a paginated list of template objects, each with a set of fields you can use to make automated decisions.

Key Fields in the Template Object

Every template object in the response includes:

• id — the unique identifier you pass to /mockups/generate

• name — a human-readable label, useful for logging and debugging

• is_user_template — boolean indicating whether this is a built-in Mockupanda template or one you uploaded yourself as a custom PSD

• Frame metadata including dimensions and aspect ratio

• Multi-frame indicators for diptych and triptych templates, which use the artwork_urls array in generation requests

For most automated workflows, you only need the id from the top result. But the name field is worth logging so your team can audit which templates are being selected for which design categories over time. That audit trail lets you refine your queries iteratively.

When to Take the Top Result vs. Presenting Options

The right strategy depends on your use case.

For a fully automated pipeline that is generating mockups for a large catalog with no human in the loop, taking the top result and moving on is usually the right call. The semantic ranking is reliable enough that the first result will be the best fit for a well-formed query, especially when combined with dimension filters.

For a semi-automated tool where a human reviews selections before generation, returning the top three to five results and displaying their names or preview URLs gives the reviewer just enough to make a fast choice without scrolling through the full library. This is the middle ground between full automation and manual browsing, and it is a significant time saver even if it is not zero-touch.

Actionable takeaway: Build your query construction logic first. The better your queries, the higher your confidence in taking the top result automatically. Start with top-three selection with human review, measure how often the reviewer changes the selection, and graduate to top-one automation once you see that rate drop below a threshold you are comfortable with.

Building a Complete Automated Mockup Pipeline

Now that you understand search, filters, and response handling, here is how all the pieces connect into a real pipeline using Mockupanda's API.

The Four-Step Pipeline Pattern

Step 1: Upload or reference the artwork URL. Mockupanda's generate endpoint accepts an artwork_url parameter, so you do not need a separate upload step if your artwork is already hosted somewhere accessible. Pass the URL directly.

Step 2: Query for templates using semantic search. Construct your q string from your design's metadata (category, style, color palette description), combine it with match_artwork=true, and call GET /templates. Cache the response for a short window if you are processing many designs with the same category tag.

Step 3: Pass the template IDs to /mockups/generate. Take the top one, two, or three template IDs from your search results and pass them as the template_ids array in a single POST /mockups/generate request. The API supports up to 12 template IDs per batch request, so you can generate multiple mockup variations in one call.

Step 4: Store or distribute the output URLs. The generate endpoint returns image URLs you can download, store in your asset management system, or push directly to your Etsy or Shopify listing workflow.

Rate limits sit at 100 requests per minute and 10,000 requests per day per API key, which is more than enough for most catalog scaling operations. And since failed requests cost zero credits, you can build retry logic without worrying about being charged for errors.

Handling Multi-Frame Templates in Search Results

If your search returns a multi-frame template (a diptych or triptych), the generation call works slightly differently. Instead of a single artwork_url, you pass an artwork_urls array with one URL per frame. Make sure your pipeline checks the frame count in the template response and prepares the correct number of artwork URLs before calling generate.

For most print-on-demand sellers working with single-image designs, multi-frame templates are not always relevant. But if you are selling sets or series, they are worth identifying in your search results and routing to a separate generation path that handles the multi-URL requirement.

Actionable takeaway: Map out your pipeline as a flowchart before writing code. Identify the branch points (single-frame vs. multi-frame, human review vs. fully automated) and handle them as separate paths from the start. It is much easier to build that branching logic in the design phase than to retrofit it into a script that only handles the simple case.

Saving Frequently Used Template Groups With Sets

Once you have found templates that work consistently well for specific design categories through semantic search, there is a smarter way to handle repeat runs than querying every time: Sets.

What Sets Are and When to Use Them

A Set in Mockupanda is a named, ordered group of templates you save in the app. Instead of specifying individual template_ids in every API request, you pass a single set_id and the API renders all templates in that set for your artwork.

The workflow is: use semantic search to discover the right templates for a category once, save them as a Set through the web app or note the IDs, then use the set_id in all future automated requests for that category. Your pipeline simplifies from a two-step process (search then generate) to a one-step process (generate with set) for established categories.

You can retrieve your sets via GET /sets and individual set details via GET /sets/{id}, both of which return the ordered list of template IDs so you can inspect and update them if your preferred templates change over time.

Combining Sets With Semantic Search for New Categories

A mature pipeline uses both features in complementary ways. For design categories you have already optimized, generate against a saved Set. For new design styles or product types that do not fit any existing Set, run semantic search to discover candidates, review results, and either use them immediately or create a new Set for that category going forward.

This hybrid approach means semantic search does the discovery work once, and Sets do the heavy lifting for all subsequent volume. Over time your library of Sets grows to cover your entire catalog, and the search step becomes less frequent.

Actionable takeaway: After your first successful semantic search run for a new category, immediately save the winning template IDs as a named Set in the Mockupanda web app. Label it with the design category and aspect ratio so your team can identify it later. That 30-second step eliminates repeated search calls for every future design in that category.

A Note on API Pricing and What It Means for Scaling

Before you commit to any API-based automation, it helps to know what it will cost at volume. Mockupanda prices API usage at 1 credit per mockup, and 1 credit equals $0.01. That means 1,000 mockups cost $10, and 10,000 cost $100.

Credits never expire, and failed requests cost zero credits, which means you can build robust retry logic and exploratory queries without losing money on errors. Top-ups start at $1.00 and go up to $1,000 per transaction through Stripe, and you can check your current balance at any time via GET /billing/wallet.

For a seller generating 500 new mockups per month across a growing catalog, the API cost works out to $5 per month. For a POD business generating 5,000 mockups, that is $50. Compared to the staff time saved by eliminating manual template browsing at that volume, the economics are straightforward.

Actionable takeaway: Before your first production run, calculate your expected monthly mockup volume and the corresponding credit cost. Top up accordingly, and build a balance check into your pipeline's startup routine using GET /billing/wallet so you catch low-balance situations before they interrupt a run.

Semantic search is one of those API features that looks like a small convenience until you actually need to process hundreds of designs without a human in the loop, and then it becomes the thing the whole pipeline depends on. The combination of plain-language queries, aspect ratio filtering, and artwork dimension matching means you can go from design file to rendered mockup URLs in a fully automated sequence, with no manual browsing, no template guesswork, and no bottleneck at the discovery step.

If you are ready to start building, the API documentation at Mockupanda includes code samples in cURL, JavaScript, Python, Node.js, and PHP to get your first request running in minutes.