Search Products By Uploaded Image
products.search.image_uploadUpload a local image file (or base64 string) and search PoloPan catalog products using visual image similarity. Returns matching products with available in-stock sizes, pricing, and verified purchase URLs (https://s.polopan.com/p/{handle}). Automatically localized to active country / 240+ destination regions.
PURPOSE & DISAMBIGUATION:
Performs reverse visual search by uploading a local or base64-encoded image to secure temporary storage, then querying visual embeddings.
Distinct from 'products.search.image_url': Use this tool when the image file is local on the user's machine or in base64 format, NOT already on a public URL.
Distinct from 'vision.outfit.detect_pieces': Use this tool to search for products matching a single garment, NOT for decomposing full multi-piece outfits into bounding boxes.
WHEN TO USE:
When a user uploads a local photo/screenshot or supplies base64 image data to find matching fashion products in the catalog.
WHEN NOT TO USE:
Do NOT use when the image is already accessible via a public web URL (use 'products.search.image_url').
Do NOT use for text-only searches (use 'products.search.text').
BEHAVIOR & SAFETY:
Read-only catalog query with temporary image upload artifact (automatically expires after 'expiry_hours', default 24h).
Resolves MIME types automatically if not explicitly provided.
Enriches all returned items with verified PoloPan purchase links and stock metadata.
PARAMETERS & CONSTRAINTS:
'image_path' (string, optional): Local file system path to the image file (one of image_path or image_base64 is required).
'image_base64' (string, optional): Base64-encoded image data string.
'country' (string, optional): Target country name, city, currency, or ISO-2 code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.
'mode' (enum, optional): Catalog mode: 'global' (ships to country) or 'local' (domestic only).
'content_type' (string, default 'image/jpeg'): MIME type of the uploaded image (e.g. 'image/jpeg', 'image/png', 'image/webp').
'expiry_hours' (integer 1-168, default 24): Temporary upload lifetime in hours before expiration.
'page' (integer >= 1, default 1): Pagination page number.
'page_size' (integer 1-100, default 20): Number of items per page.
'sort_by' (enum, default 'relevance'): Sorting attribute ('relevance', 'price', 'title').
'sort_order' (enum, default 'desc'): Sort direction ('asc' or 'desc').
'gender' (string, optional): Target gender filter ('men', 'women', or 'unisex').
'size' (array of strings, optional): Size filter array.
'price_min' (number, optional): Minimum price threshold.
'price_max' (number, optional): Maximum price threshold.
'vendor' (array of strings, optional): Brand filter array.
'personalize' (boolean, default false): Whether to personalize search ranking.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region. | |
| page | No | Pagination page number (1-indexed) | |
| size | No | Array of sizes to filter by | |
| gender | No | Target gender filter: 'men', 'women', or 'unisex' | |
| vendor | No | List of brand names to filter by | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| sort_by | No | Sorting criteria: 'relevance', 'price', or 'title' | relevance |
| page_size | No | Number of items to return per page (1 to 100, default 20) | |
| price_max | No | Maximum price in local currency | |
| price_min | No | Minimum price in local currency | |
| image_path | No | Local file system path to the image file (e.g. '/path/to/dress.jpg') | |
| sort_order | No | Sort order: 'asc' or 'desc' | desc |
| personalize | No | Whether to apply personalized ranking weights | |
| content_type | No | MIME type of the image, e.g. 'image/jpeg', 'image/png', 'image/webp' | image/jpeg |
| expiry_hours | No | Temporary upload URL lifetime in hours before expiration (1 to 168, default 24) | |
| image_base64 | No | Base64-encoded image data string (alternative to image_path) |