Fashion Search
To access the Ximilar API, first register at Ximilar App to get your API token. This API follows the general rules of Ximilar API as described in Section First steps.
With Fashion Search API, customers can upload images to retrieve visually similar fashion products from your catalog. The service combines visual search with Fashion Tagging and Dominant Colors.
It works with real-life photos, social media images, and screenshots, and supports both image-based and multilingual text-based search.
How It Works
To use the API:
- Create a collection in Ximilar App — you’ll get a unique collection ID to include in all requests.
- Insert products — add records (image + metadata +
_id
). Processing and indexing run automatically. - Keep it synced — schedule automatic synchronization runs at your chosen cadence (e.g., hourly/daily) to add, update, or remove items as your catalog changes. See Synchronization.
Once setup, you can:
- Search fashion apparel: Input a product or real-life image, and the system finds closest matches.
- Recommend products: Suggest visually similar items to users based on their browsing or purchase history.
- Use text search: Send queries in any language to find matching products in your collection.
This service is available in paid pricing plans. For more information, see Pricing page.
Endpoints
The URLs for this service are:
https://api.ximilar.com/similarity/fashion-new/v2/insert (insert images and metadata into collection)
https://api.ximilar.com/similarity/fashion-new/v2/visual_search (perform image-based search)
https://api.ximilar.com/similarity/text/fashion/v2/text (perform text-based search)
Synchronization
Add images (products) to your Fashion Search collection. Each inserted record is processed as follows:
- Detect fashion items in the photo.
- Optionally analyze product colors and assign tags.
- Extract visual features (embedding) from the largest detected item.
- Store the embedding together with your metadata in the collection.
Your images are processed once and then discarded. Only the extracted features and metadata are stored for search.
Required attributes
- Name
Authorization
- Type
- string
- Description
Your API token in the format:
Token YOUR_API_TOKEN
.
- Name
collection-id
- Type
- string
- Description
Your collection ID.
Request parameters
- Name
records
- Type
- array
- Max
- Maximum:10
- Description
List of records to insert (max 10 per request).
- Name
records[]._id
- Type
- string
- Description
Unique identifier for the record.
- Name
records[]._url
- Type
- string
- Description
URL with a PNG, JPG, or TIFF image file.
- Name
records[]._base64
- Type
- string
- Description
Base64-encoded content of a PNG, JPG or TIFF image file.
- Name
records[].Top Category
- Type
- string
- Description
Top category according to Ximilar Fashion Taxonomy.
- Name
records[].Category
- Type
- string
- Description
Category according to Ximilar Fashion Taxonomy.
- Name
records[].extract_colors
- Type
- boolean
- Description
If set to
true
, the system will extract dominant colors for the item. This will consume additional API credits as per the Dominant Colors pricing.
- Name
records[].extract_tags
- Type
- boolean
- Description
If set to
true
, the system will extract relevant tags for the item. This will consume additional API credits as per the Fashion Tagging pricing.
- Name
records[]._tags_simple
- Type
- array
- Description
Custom tags for the record.
Request
curl --request POST \
--url https://api.ximilar.com/similarity/fashion-new/v2/insert \
--header 'authorization: Token __API_TOKEN__' \
--header 'collection-id: __COLLECTION_ID__' \
--header 'content-type: application/json' \
--data '{
"records": [
{
"_id": "ABC_1",
"_url": "https://example.com/product/image/url.png",
"Top Category": "Clothing",
"Category": "Clothing/Pants",
"extract_colors": true,
"extract_tags": true,
"_tags_simple": ["yellow", "stilleto", "women"]
}
]
}'
Response
{
"status": {
"code": 200,
"text": "OK"
},
"records": [
{
"_id": "ABC_1",
"_url": "https://example.com/product/image/url.png",
"_status": {
"code": 200,
"text": "OK"
}
}
]
}
Visual Search
Search for similar fashion products using a photo. The system will:
- Detect all fashion items in the query photo
- Return similar products to the largest detected item
Required attributes
- Name
Authorization
- Type
- string
- Description
Your API token in the format:
Token YOUR_API_TOKEN
.
- Name
collection-id
- Type
- string
- Description
Your collection ID.
Request parameters
- Name
query_record
- Type
- object
- Description
Record containing the image to search with.
- Name
query_record._url
- Type
- string
- Description
URL with a PNG, JPG, or TIFF image file.
- Name
query_record._base64
- Type
- string
- Description
Base64-encoded content of a PNG, JPG or TIFF image file.
- Name
fields_to_return
- Type
- array
- Description
List of fields to return in results.
- Name
filter
- Type
- object
- Description
MongoDB-style filter for results.
- Name
k
- Type
- integer
- Description
Number of results to return.
Response fields
- Name
query_records
- Type
- array
- Description
The query record with detected objects.
- Name
query_records[]._objects
- Type
- array
- Description
An array of detected fashion items.
- Name
answer_records
- Type
- array
- Description
An array of similar products.
- Name
answer_distances
- Type
- array
- Description
An array of similarity scores.
Request
curl --request POST \
--url https://api.ximilar.com/similarity/fashion-new/v2/visualKNN \
--header 'authorization: Token __API_TOKEN__' \
--header 'collection-id: __COLLECTION_ID__' \
--header 'content-type: application/json' \
--data '{
"query_record": {
"_url": "https://example.com/image.png"
},
"fields_to_return": ["_id", "_url", "product_id"],
"k": 5
}'
Response
{
"query_records": [
{
"_id": "49831",
"_url": "https://example.com/image.png",
"_objects": [
{
"area": 0.696093738079071,
"prob": 0.9520546793937683,
"Top Category": "Clothing",
"Category": "Clothing/Jackets and Coats",
"bound_box": [49, 3, 346, 378],
"_tags": {
"detailed tag list": true
},
"_tags_simple": ["simple tag list"]
}
]
}
],
"answer_records": [
{
"_id": "294215",
"_url": "https://images.ximilar.com/fashion/Clothing/Pullover/Knit sweater/v70kjnwe53sz4may/v70kjnwe53sz4may_1.jpg"
}
],
"answer_distances": [0.64635134],
"answer_count": 1,
"status": {
"code": 200,
"text": "OK"
}
}
Text Search
Perform multilingual text search (visual similarity/KNN) on your collection of images via text query.
Required attributes
- Name
Authorization
- Type
- string
- Description
Your API token in the format:
Token YOUR_API_TOKEN
.
- Name
Collection-Id
- Type
- string
- Description
Your collection ID.
Request parameters
- Name
query_record
- Type
- object
- Description
Record containing the text query.
- Name
query_record._text_data
- Type
- string
- Description
Text query in any language.
- Name
fields_to_return
- Type
- array
- Description
List of fields to return in results.
- Name
filter
- Type
- object
- Description
MongoDB-style filter for results.
- Name
k
- Type
- integer
- Description
Number of results to return.
Response fields
- Name
answer_records
- Type
- array
- Description
An array of matching products.
- Name
answer_distances
- Type
- array
- Description
An array of similarity scores.
Request
curl --request POST \
--url https://api.ximilar.com/similarity/text/fashion/v2/text \
--header 'authorization: Token __API_TOKEN__' \
--header 'collection-id: __COLLECTION_ID__' \
--header 'content-type: application/json' \
--data '{
"query_record": {
"_text_data": "a blue pullover with white stripes pattern"
},
"fields_to_return": ["_id", "_url", "supplierid"],
"filter": {
"supplierid": {
"$lte": 600
}
},
"k": 3
}'
Response
{
"status": {
"code": 200,
"text": "OK"
},
"answer_records": [
{
"_id": "65732555",
"_url": "_URL_1_",
"supplierid": 450
}
],
"answer_distances": [1.1622182],
"answer_count": 1
}
Multiple Images per Product
To insert multiple images for the same product, specify the same product_id
for each record with the identification number of the product.
You must also specify this product_id
field in the collection settings in Ximilar App.
All records must have the product_id
field present in your collection if you
turn on this setting, otherwise the search responses will return an error.
Example Request
{
"records": [
{
"_id": "__IMAGE_ID__",
"_url": "__IMAGE_URL__",
"product_id": "1"
},
{
"_id": "__IMAGE_ID__",
"_url": "__IMAGE_URL__",
"product_id": "1"
},
{
"_id": "__IMAGE_ID__",
"_url": "__IMAGE_URL__",
"product_id": "1"
}
]
}
Top Category and Category
Sometimes it is difficult to correctly identify the main item in a product image and its category. You can help Ximilar by providing the Top Category (and Category) of the product. These must follow the Ximilar Fashion Taxonomy and be included in each inserted image record.
If you specify the Top Category and Category, the insert operation will not necessarily select the largest detected object, but rather the largest object matching the provided Top Category (and Category). If no such object is detected, Ximilar will treat the whole image as a fashion item and use the Fashion Tagging method to determine its categories and tags.
Filtering with Categories
You can also filter search results using the Top Categories
and Categories
fields.
In a search request, you may specify multiple categories, and the system will:
- Filter objects by the provided
Top Categories
andCategories
lists - Prioritize objects that match the specified
Top Category
- Return results that match any of the specified categories
This is particularly useful when searching for items that could belong to multiple categories, or when you want to prioritize certain categories in the results.
Example Request
{
"records": [
{
"product_id": "ABC",
"_id": "ABC_1",
"_url": "https://example.com/product/image/url.png",
"Top Category": "Clothing",
"Category": "Clothing/Pants"
}
]
}
Search with Category Filtering
curl --location 'https://api.ximilar.com/similarity/fashion-new/v2/visualKNN' \
--header 'Authorization: Token APITOKEN' \
--header 'collection-id: COLLECTIONID' \
--header 'Content-Type: application/json' \
--data '{
"query_record": {
"_url": "https://images.ximilar.com/examples/fail/footwearx.jpg",
"Top Categories": ["Footwear", "Clothing"],
"Categories": ["Clothing/Jackets and Coats", "Footwear/Pumps"],
"Top Category": "Footwear"
},
"fields_to_return": [
"_id",
"_url"
],
"k": 10,
"cand_set_size": 5000
}'
Search With Specific Object
If you want to search for products similar to an object other than the main (largest) one,
you can do this by passing the query object with the _objects
field pre-filled with the secondary object.
This is useful when a photo contains multiple fashion items and you want to focus on a specific one.
Make sure to copy the full JSON record of the object (including all fields) from the API response when specifying the object to search for.
Workflow with Fashion Detection
You can combine the Fashion Detection and the visual search as follows:
- Call the Fashion Detection method to detect all fashion items in the photo (without immediately retrieving similar products).
- Let the user select the item they are interested in.
- Use the selected object’s JSON record in a subsequent visual search query.
Mobile App Integration
If you want to integrate fashion search into a mobile app and allow users to draw/select the object, specify it using a bounding box. The format of the bounding box is: [xmin, ymin, xmax, ymax].
Example Request
curl --request POST \
--url https://api.ximilar.com/similarity/fashion-new/v2/visualKNN \
--header 'authorization: Token __API_TOKEN__' \
--header 'collection-id: __COLLECTION_ID__' \
--header 'content-type: application/json' \
--data '{
"query_record": {
"_url": "https://example.com/image.png",
"_objects": [
{
"area": 0.376093738079071,
"prob": 0.9120546793937683,
"Top Category": "Clothing",
"Category": "Clothing/Pants",
"bound_box": [349, 23, 646, 378]
}
]
},
"fields_to_return": ["_id", "_url", "product_id"]
}'
Python Example
from ximilar.client.search import SimilarityFashionClient
client = SimilarityFashionClient(token='__API_TOKEN__', collection='__COLLECTION_ID__')
result = client.search([{
"_url": "__URL_PATH_TO_IMAGE__",
"_objects": [
{
"area": 0.376093738079071,
"prob": 0.9120546793937683,
"Top Category": "Clothing",
"Category": "Clothing/Pants",
"bound_box": [349, 23, 646, 378]
}
]
}])
Mobile App Example
{
"records": [
{
"_url": "__URL_IMAGE__",
"_objects": [
{
"bound_box": [701, 1760, 1155, 1952]
}
]
}
]
}