How to Use the Mockupanda API's Artwork-Matching Filter to Skip Templates That Don't Fit Your Design's Proportions

If you have ever generated a batch of mockups only to find half of them look off, you already know the cause: the artwork's proportions did not match the template's frame. A 2:3 portrait design dropped into a 3:2 landscape scene gets cropped or stretched, and the result looks wrong immediately. Fixing it after the fact means rerunning those renders and spending more credits.

The better approach is to filter at the template discovery stage, before you ever call POST /mockups/generate. Mockupanda's GET /templates endpoint has a set of artwork-matching parameters that do exactly this: you describe your artwork, and the API returns only the print templates shaped for it. No manual ratio checking, no wasted renders, no cropped listing images.

This guide covers every parameter involved, the two-step workflow that makes bulk catalog generation reliable, and the edge cases worth knowing about.

Why Proportion Mismatches Happen and Why They Matter

The API Does Not Guess Your Intention

When you send an artwork to POST /mockups/generate, the API places it into the template's frame. If the artwork's aspect ratio does not match the frame's expected ratio, the API centers the artwork and crops or stretches it to fill the frame. You just get a mockup where part of your design is missing or distorted.

For a single render that is easy to catch. For a catalog of hundreds of designs across dozens of templates, it is a systematic problem. You end up with a subset of your mockups that are silently wrong.

The Credit Cost of Getting It Wrong

Every successful render costs one credit, which is $0.01 on Mockupanda's API. Failed requests cost nothing, but a render that completes with a cropped or stretched result is not a failed request from the API's perspective: it succeeded. You pay for it. At scale, sending designs to templates that do not fit their proportions adds up quickly, both in credits spent and in time spent reviewing outputs.

The artwork-matching filter moves the check to the template discovery step, before any mockup is rendered. You query the template list, get back only the templates that fit your artwork, and then generate. Zero wasted renders.

What the Docs Say About Mismatches

The Mockupanda API documentation is direct about this: artwork that does not match the expected ratio is cropped or stretched to fill the frame, which is exactly the thing that makes a mockup look wrong. The recommended fix is to ask for the templates that fit, rather than checking ratios yourself.

Takeaway: Before you generate a single mockup, use the template list endpoint to narrow down to templates that actually fit your artwork. It happens before any render and prevents the most common source of bad outputs.

The Two Parameters That Do the Work

artwork_url: Let the API Measure Your File

The simplest way to use artwork-matching is to pass your artwork's public URL as the artwork_url query parameter on GET /templates. The API reads the image header to determine the artwork's pixel dimensions, derives its aspect ratio, and returns only the print templates within a matching tolerance.

You can combine it with other filters. Here is an example that also narrows results to bedroom scenes using the semantic search parameter q:

curl -X GET "https://www.mockupanda.com/api/v1/templates?artwork_url=https://example.com/art.png&q=bedroom" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes an artwork object that tells you exactly what the API detected:

{
  "artwork": {
    "width": 4000,
    "height": 6000,
    "format": "png",
    "ratio": 0.667,
    "name": "2:3",
    "orientation": "portrait",
    "label": "2:3 portrait"
  }
}

It also includes a ratio_filter object confirming what was applied:

{
  "ratio_filter": {
    "requested": ["2:3"],
    "tolerance_percent": 3,
    "applied_to": "print"
  }
}

This tells you the filter ran on print templates, matched the 2:3 ratio family, and applied the default 3% tolerance. You do not have to figure out what ratio your artwork is: the API does it and tells you.

One important implementation detail: the API only downloads the image header, not the full file. That means passing a 20 MB PNG costs no more in time or resources than passing a 50 KB thumbnail. File size does not affect how quickly the template list comes back.

artwork_width and artwork_height: Skip the Download Entirely

If you already know your artwork's pixel dimensions, you do not need to pass a URL at all. Use artwork_width and artwork_height as integers instead:

curl -X GET "https://www.mockupanda.com/api/v1/templates?artwork_width=4000&artwork_height=6000&q=bedroom" \
  -H "Authorization: Bearer YOUR_API_KEY"

This produces identical filtering behavior without any network request to fetch even the image header. It is the faster option when your artwork metadata is already in your database or your build pipeline.

For a catalog workflow where you store artwork dimensions alongside artwork URLs, this is the preferred approach. Query your database for the dimensions, pass them directly to the template list, and avoid an extra round-trip entirely.

Takeaway: Use artwork_url when dimensions are not stored and you need the API to detect them. Use artwork_width and artwork_height when dimensions are already known. Both produce identical filtering results.

Understanding the Tolerance Setting

Why a 3% Default Exists

Artwork ratios in the real world are rarely perfect. A design intended to be 2:3 might be exported at 2000x2999 pixels because of a rounding difference in a design tool. A template frame hand-traced from a photograph might be 2:2.98 rather than exactly 2:3. If the filter required a perfect ratio match, it would reject templates and artwork that are functionally identical.

The default ratio_tolerance of 3% absorbs these small differences. A template with an aspect ratio within 3% of your artwork's ratio is returned as a match. A template that is 3:4 is not returned for a 2:3 artwork, because the difference is well outside 3%. The tolerance is wide enough to handle real-world imprecision but narrow enough to exclude genuinely different proportions.

When to Raise the Tolerance

The ratio_tolerance parameter accepts values up to 25. You would raise it in situations where you would rather have a slight crop than no mockup at all. For example, if your catalog includes designs that are close to 4:5 but not exactly, and you want them to appear in 2:3 templates where the crop would be minimal and aesthetically acceptable, you can raise the tolerance to 10 or 15.

Be deliberate about this. A higher tolerance means more templates are returned, but some of those templates will crop your artwork more noticeably. If your designs have important content near the edges, a 15% tolerance mismatch will cut into it.

curl -X GET "https://www.mockupanda.com/api/v1/templates?artwork_url=https://example.com/art.png&ratio_tolerance=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Prints Only: Why Product Templates Are Excluded

Ratio filtering applies only to print templates. This is intentional and enforced by the API. Product templates, which cover apparel, mugs, tote bags, and other 3D surfaces, warp artwork onto curved surfaces using UV mapping. There is no fixed artwork ratio for a t-shirt print area the way there is for a poster frame. As a result, any request that combines an artwork or ratio filter with type=product returns a 400 error.

If you are building a workflow that handles both print and product templates, keep them in separate requests. Use the artwork-matching filter for your poster and wall art runs, and query product templates separately without ratio parameters.

Takeaway: The default 3% tolerance handles normal artwork imprecision. Raise it deliberately when a slight crop is acceptable. Keep print and product template queries separate.

The Full Two-Step Bulk Workflow

Step One: Discover Matching Templates

The reliable pattern for bulk catalog rendering is to run two API calls per artwork: first list the templates that fit it, then generate mockups using those template IDs.

Here is the discovery step in full. This example queries for templates matching a 4000x6000 artwork, searches for living room scenes, and uses the default tolerance:

curl -X GET "https://www.mockupanda.com/api/v1/templates?artwork_width=4000&artwork_height=6000&q=living+room" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response comes back with only the templates shaped for a 2:3 portrait artwork. You collect the id values from the templates array. In the example response from the documentation, with a 4000x6000 artwork and a bedroom query, 11 templates matched. That is the filter doing its job.

You can combine the artwork-matching parameters with the semantic search parameter q and any other filters available on GET /templates, including category, source, and type. Combining artwork_url or the dimension parameters with type=print is redundant but harmless since the filter already restricts to print templates. What you cannot do is combine them with type=product.

For catalogs where designs come in multiple sizes, you can also pass a comma-separated list of ratios using the ratio parameter. For example, ?ratio=2:3,4:5 returns templates that fit either portrait ratio, which is useful when your artwork set includes both shapes and you want a single query to surface the union of matching templates. The aspect-ratio filter documentation covers named ratio syntax in detail, including print size names like 8x10, paper sizes like A4, and plain orientation words like portrait.

Step Two: Generate with Matching Template IDs

Once you have the template IDs from step one, pass them to POST /mockups/generate. The batch mode accepts up to 12 template IDs per request, which you can combine with Mockupanda's batch generation approach to minimize the number of API calls for large template sets.

curl -X POST https://www.mockupanda.com/api/v1/mockups/generate \
  --http1.1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_ids": ["bedroom-poster-01", "frame-wall-02", "living-room-03"],
    "artwork_url": "https://example.com/art.png",
    "response_format": "json"
  }'

Because the template IDs came from a filtered list that already matched the artwork's proportions within the tolerance, every render in this batch fits the artwork's shape, with at most a slight crop.

The batch response returns one result object per template:

{
  "success": true,
  "count": 2,
  "results": [
    {
      "template_id": "bedroom-poster-01",
      "image": "/9j/4AAQSkZJRg...",
      "format": "jpeg",
      "content_type": "image/jpeg",
      "size_bytes": 523481
    },
    {
      "template_id": "frame-wall-02",
      "image": "/9j/4AAQSkZJRg...",
      "format": "jpeg",
      "content_type": "image/jpeg",
      "size_bytes": 498210
    }
  ]
}

If your filtered list returns more than 12 templates, split them into groups of 12 and run sequential batch requests. Each request stays within the batch limit and reuses the same artwork URL.

Takeaway: The two-step workflow, discover then generate, is the production-ready pattern for catalog rendering. Step one renders nothing. Step two only spends credits on renders you know will fit.

Combining Artwork-Matching with Other Filters

Pairing with Semantic Search

The artwork-matching filter works alongside the q parameter, which runs a hybrid semantic search across the template library. This means you can simultaneously filter by proportion and by scene type. A query like ?artwork_url=https://example.com/art.png&q=minimalist+studio returns only the templates that are both shaped for your artwork and semantically relevant to minimalist studio settings.

For sellers who have strong visual branding and want their designs shown in consistent settings, this combination is powerful. You are not browsing a library manually or filtering by category name alone. The semantic search parameter finds templates by meaning, so queries like "beige bedroom" or "sunlit room" work even when those exact words are not in the template name.

The relevance_ranked field in the response tells you whether the results are sorted by semantic relevance, so check it rather than assuming the order.

Using Named Ratios When You Know the Shape in Advance

When you know your artwork's target ratio before you have a file URL, use the ratio parameter directly instead of artwork_url. Named formats cover common print sizes and orientations:

• Standard ratios: 2:3, 3:2, 4:5, 16:9

• Print sizes: 8x10, 11x14, 18x24, 24x36

• Paper sizes: A4, US Letter

• Orientations: portrait, landscape, square

• Decimal: 0.667

Comma-separate multiple values to accept more than one shape in a single query. This is the right tool when you are designing your catalog structure and know upfront which shapes you will produce, before the actual artwork files exist.

The artwork_url and dimension parameters are better when you are processing existing files programmatically and cannot know the ratios in advance without inspecting the files yourself.

Storing Template Sets for Reuse

If your catalog has consistent artwork shapes, you do not need to rediscover templates on every run. After running the two-step workflow once and identifying which templates consistently match your most common artwork ratios, you can save those template IDs as a Set in Mockupanda. Sets let you store a named, ordered group of templates and render them via a single set_id parameter. This is useful when your artwork shape does not change run to run and you have already curated the best matching templates.

For dynamic catalogs where artwork proportions vary across designs, run the discovery step per design rather than per session.

Takeaway: Layer semantic search on top of artwork-matching for scene-specific filtering. Use named ratios when you know the shape in advance. Cache template IDs as Sets when your catalog shape is consistent across runs.

A Complete Python Example

Building the Discovery Function

Here is a minimal Python function that takes an artwork URL, an optional scene description, and returns a list of matching template IDs:

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://www.mockupanda.com/api/v1"

def get_matching_templates(artwork_url, query=None, tolerance=3):
    params = {
        "artwork_url": artwork_url,
        "limit": 50,
        "ratio_tolerance": tolerance
    }
    if query:
        params["q"] = query

    response = requests.get(
        f"{BASE_URL}/templates",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params
    )
    response.raise_for_status()
    data = response.json()
    return [t["id"] for t in data["templates"]]

This returns a plain list of template IDs. If the library has more than 50 matching templates, increment the page parameter and repeat until pagination.total_pages is exhausted.

Building the Generation Loop

Once you have the matching template IDs, split them into chunks of 12 and run a batch generate call per chunk:

import math

def generate_mockups(artwork_url, template_ids):
    chunk_size = 12
    chunks = [
        template_ids[i:i + chunk_size]
        for i in range(0, len(template_ids), chunk_size)
    ]
    all_results = []
    for chunk in chunks:
        payload = {
            "template_ids": chunk,
            "artwork_url": artwork_url,
            "response_format": "json"
        }
        response = requests.post(
            f"{BASE_URL}/mockups/generate",
            headers={
                "Authorization": f"Bearer {API_KEY}",
                "Content-Type": "application/json"
            },
            json=payload
        )
        response.raise_for_status()
        data = response.json()
        all_results.extend(data["results"])
    return all_results

Calling these two functions in sequence, get_matching_templates then generate_mockups, gives you a complete, proportion-safe bulk rendering pipeline. Every mockup in all_results came from a template that the API confirmed fits the artwork's shape.

Takeaway: A two-function Python structure, one for discovery and one for generation, maps cleanly onto the two-step API workflow and handles catalogs of any size by paginating template discovery and chunking generation into batches of 12.

Common Mistakes and How to Avoid Them

Skipping the Discovery Step

The most common mistake is sending artwork directly to a fixed list of template IDs without checking proportions first. This works fine when your templates and artwork are curated together manually, but it breaks down as soon as your catalog grows or your artwork shapes vary. If you add a new template to your list that expects a different ratio, every design that does not match it starts producing cropped mockups silently.

The discovery step protects you from this. Even if your template library changes, the filter ensures that only the currently matching templates make it into your generation calls.

Combining Artwork Filters with Product Templates

Passing artwork_url or artwork_width and artwork_height alongside type=product returns a 400 error. Product templates use UV mapping and do not have a fixed artwork ratio, so the filter has no meaningful definition there. If your workflow handles both print and product templates, run them as separate queries. Discovery for print templates uses artwork-matching. Discovery for product templates queries by category or scene without ratio parameters.

Using a Tolerance That Is Too High

Setting ratio_tolerance to 20 or 25 to maximize the number of returned templates means accepting templates where your artwork will be noticeably cropped. If your design has a subject centered in the frame with significant empty space around it, a high tolerance crop might be invisible. If your design has fine detail or text running to the edges, it will not. Set the tolerance at the level that reflects your artwork's actual margin for cropping.

Takeaway: Use the discovery step consistently, keep print and product template queries separate, and set tolerance based on how close to the edges your artwork's important content sits.