Pinterest visual search ads: how many image variants per call?

You can request up to 10 images per POST /v1/images call with the n field, but each model's own ceiling is lower, and you read it from the catalog before you plan. A trade tracker lists Pinterest visual search ads as a planned beta (read 2026-10-06); if you want several candidate images per product to test once it opens, the n range descriptor tells you how many one call can return.

Facts from Image API: generate and edit images and the Social media platform updates, October 2026 (read 2026-10-06).

Where to read the ceiling

Each model has an endpoint record at GET /v1/images/models/{model_id}/endpoints. Its supported_parameters use typed descriptors: enum for a list of allowed strings, range for integers between a min and max, boolean for a yes or no. n is a range, so read max. In v1 every catalog model is served through one sume endpoint, so the model-level and endpoint-level parameters are identical.

What the docs show for n

The Image API page shows a sample model record for bytedance-seed/seedream-4.5 where n is a range from 1 to 4 and input_references is a range from 0 to 10. Treat that as an illustration of the shape, not as a promise for any other model; the 10-per-call figure is the outer limit on the request, and each model lists its own ceiling (Image API: generate and edit images).

A model that lists n with a max of 4 will get a 400 unsupported_parameter style rejection if you ask for more, because the API rejects a request that sets a parameter the model does not advertise instead of dropping it silently. Build the planner so it reads the descriptor, clamps its own batch size to max, and never relies on the server to trim.

Large n also changes timing. The docs say POST /v1/images blocks for up to 30 seconds and that slow configurations, including 4K, high quality and large n, are the most likely to come back as a 202 job envelope instead of a finished image. A planner that asks for the maximum n at high quality should be written to poll GET /v1/jobs/{id}/status and fetch /result, not to assume a 200.

Plan the set from the number

Say you want six variants for each of 40 products: two angles, three backdrops. If the ceiling is 4, that is two calls per product, 80 calls. If it is 1, it is 240 calls. The count of calls drives wall-clock time and retries, while the image count drives cost. Cost per image comes from the endpoint's pricing lines, which you read the same way, so you can multiply before you send anything.

A request that sets a parameter outside what the model lists is rejected, not clipped. That is useful: your planner finds out at the first call, not after paying for a partial set.

import json, os, urllib.request

MODEL = "openai/gpt-image-2.5"
req = urllib.request.Request(
    "https://api.sume.com/v1/images/models/" + MODEL + "/endpoints",
    headers={"Authorization": "Bearer " + os.environ["SUME_API_KEY"]},
)
with urllib.request.urlopen(req) as r:
    rec = json.load(r)

endpoints = rec.get("endpoints") or rec.get("data", {}).get("endpoints", [])
n = endpoints[0]["supported_parameters"].get("n", {})
ceiling = n.get("max", 1)
products, variants = 40, 6
calls_per_product = -(-variants // ceiling)
print("ceiling", ceiling, "calls", products * calls_per_product)

A worked table

The arithmetic below uses made-up ceilings only to show the shape of the plan; read your model's real value from its record. Calls are the rounded-up division of variants by the ceiling, times products.

What to do with the variants

Name each variant after the product and the scene, store the returned media.sume.com URL and tag the prompt that made it, so that when Pinterest opens its beta you can match results back to the prompt that produced the winner. Keep a stable key per product, per scene, so rerunning a half-finished batch continues rather than doubles.