Home Decor Tagging

Quickstart Taxonomy Articles & Guides Test in App Public Demo

To access the Ximilar API, first register at Ximilar App to get your API token. The API follows the general rules as described in the First Steps. This service is available in paid pricing plans. For more information, see Pricing page.

The Home Decor Tagging API automatically assigns categories, subcategories, and descriptive tags to home decor, furniture, and accessories. It is powered by models fine-tuned on a large dataset of home decor and furniture images. The resulting tags can be used for product search, filtering, recommendations, and more.

Results are stored in the _tags field; _tags_simple provides a simplified list of tag names. Each tag includes a probability score; only tags with probability >30% are returned.

Please note that _base64 data is not returned — use _id or another field to identify your images.

Taxonomy

Ximilar Home Decor Taxonomy includes:

Category Furniture with subcategories Seating, Tables, Storage, Bedroom, Office, and Outdoor
Category Accessories with subcategories Lighting, Mirrors, Frames, Textiles, Bathroom, Kitchenware, and Decorations
Hundreds of tags covering furniture types, lighting, decorations, utility items, materials, colors, patterns, and rooms

Endpoints

This service API has several endpoints running at URLs:

https://api.ximilar.com/tagging/homedecor/v2/top_categories  (get a list of categories)
https://api.ximilar.com/tagging/homedecor/v2/detect_tags     (detect and tag one object/image)
https://api.ximilar.com/tagging/homedecor/v2/detect_tags_all (detect and tag all objects in image)
https://api.ximilar.com/tagging/homedecor/v2/tags            (tagging without detection)
https://api.ximilar.com/tagging/homedecor/v2/detect          (detection without tagging)
https://api.ximilar.com/tagging/homedecor/v2/feedback        (send feedback)

Custom Features

The service and taxonomy are continuously improved and can be extended with new tags or features based on your needs.

Tag translations are available on request.
Custom profiles let you rename, combine, or create new tags.

For more information, contact care@ximilar.com.

GET/v2/top_categories

Taxonomy

Returns a list of all top categories and their subcategories.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The response body is a JSON object (map) with the following fields:

Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).

Request

GET

/v2/top_categories

curl --request GET \
  --url https://api.ximilar.com/tagging/homedecor/v2/top_categories \
  --header 'content-type: application/json'

Response

{
  "Furniture": [
    "Furniture/Furniture Set",
    "Furniture/Beds",
    "Furniture/Relax",
    "Furniture/Sitting",
    "Furniture/Storage",
    "Furniture/Tables"
  ],
  "Accessories": [
    "Accessories/Bathroom",
    "Accessories/Decorative",
    "Accessories/Dining & Cookware",
    "Accessories/Lighting",
    "Accessories/Mirrors",
    "Accessories/Storage",
    "Accessories/Textile"
  ]
}

POST/v2/detect_tags

Home Decor Detection and Tags

Taxonomy

Given a list of image records, this method detects objects in the image and returns tags (like the /v2/tags endpoint) for the largest or selected object. The fields _tags and _tags_simple are stored in the first detected object.

If you know the Top Category and Category, please specify them in each record to improve accuracy.

Required attributes

Name
records
Type
dict
Max
Maximum:10
Description
A batch of JSON records (max 10). Each record represents a single image, defined by _url or _base64.

Optional attributes

Name
aggregate_labels
Type
boolean
Default
Default:false
Description
If true, the records are treated as multiple photos of the same object. Tags are generated for each image separately, then aggregated into a single list for the entire batch.
Name
profile
Type
string
Description
If you have a custom tagging profile, apply its ID to transform the _tags — e.g., rename, add, or remove tags/features.
Name
language
Type
string
Description
Language code for tag translations. For more info, please contact us at care@ximilar.com.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The response body is a JSON object (map) with the following fields:

Name
records
Type
dict
Description
JSON array with the input records, each record enriched by field _objects. This endpoint always returns at least one object. If no object is found, the endpoint creates an artificial object covering the entire image.
Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).

Request

POST

/v2/detect_tags

curl https://api.ximilar.com/tagging/homedecor/v2/detect_tags -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
  "records": [
    { "_url": "https://images.ximilar.com/examples/homedecor_real/5_Unsplash.jpg" }
  ]
}'

Response

{
  "records": [
    {
      "_url": "https://images.ximilar.com/examples/homedecor/11.webp",
      "region": "generic",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "e5727342-d336-4da0-8a3f-312ecbeeee6a"
      },
      "_id": "f285cc24-076c-4dca-8bc6-1a33aaa24052",
      "_width": 1035,
      "_height": 1380,
      "_objects": [
        {
          "name": "Furniture Set",
          "id": "63b75a7f-af12-4996-9262-76b65e9efebb",
          "bound_box": [12, 300, 899, 1196],
          "prob": 0.39538151025772095,
          "area": 0.5564321221031996,
          "expand_by_bound_box": [0, 211, 987, 1285],
          "Top Category": "Furniture",
          "Category": "Furniture/Furniture Set",
          "_tags": {
            "Category": [
              {
                "name": "Furniture/Furniture Set",
                "prob": 1,
                "id": "3094d4da-3392-4c80-9e7d-fc6f8b59c0a4",
                "pre-filled": true
              }
            ],
            "Subcategory": [
              {
                "prob": 0.95088,
                "name": "Kitchen set",
                "id": "12143686-bdf8-44ad-8ca3-1808939a1c90"
              }
            ],
            "Top Category": [
              {
                "name": "Furniture",
                "prob": 1,
                "id": "ff06c568-dd14-4fb7-9eae-1a0d3c1da115",
                "pre-filled": true
              }
            ]
          },
          "_tags_map": {
            "Top Category": "Furniture",
            "Category": "Furniture/Furniture Set",
            "Subcategory": "Kitchen set"
          },
          "_tags_simple": [
            "Furniture",
            "Furniture/Furniture Set",
            "Kitchen set"
          ]
        }
      ]
    }
  ],
  "status": {
    "code": 200,
    "text": "OK",
    "request_id": "e5727342-d336-4da0-8a3f-312ecbeeee6a",
    "proc_id": "ae7ee797-e592-4d4b-bf88-58a1266fee3e"
  },
  "statistics": {
    "processing time": 2.421678066253662
  }
}

POST/v2/detect_tags_all

Detect All Objects and Tags

Quickstart

Given a list of image records, this method detects and tags all objects in the image. The fields _tags and _tags_simple are stored in the first detected object.

If you know the Top Category and Category, please specify them in each record to improve accuracy.

Required attributes

Name
records
Type
dict
Max
Maximum:10
Description
A batch of JSON records (max 10). Each record represents a single image, defined by _url or _base64.

Optional attributes

Name
profile
Type
string
Description
If you have a custom tagging profile, apply its ID to transform the _tags — e.g., rename, add, or remove tags/features.
Name
language
Type
string
Description
Language code for tag translations. For more info, please contact us at care@ximilar.com.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The response body is a JSON object (map) with the following fields:

Name
records
Type
dict
Description
JSON array with the input records, each record enriched by field _objects. This endpoint always returns at least one object. If no object is found, the endpoint creates an artificial object covering the entire image.
Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).

Request

POST

/v2/detect_tags_all

curl https://api.ximilar.com/tagging/homedecor/v2/detect_tags_all -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
  "records": [
    { "_url": "https://images.ximilar.com/examples/homedecor/2.jpeg" }
  ]
}'

Response

{
  "records": [
    {
      "_url": "https://images.ximilar.com/examples/homedecor/2.jpeg",
      "region": "generic",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "3ada7775-a2f7-4577-8109-8f3111140e2b"
      },
      "_id": "49b6cea9-7683-488d-acdf-14bc4ea9416a",
      "_width": 1024,
      "_height": 887,
      "_objects": [
        {
          "name": "Mirrors & Frames",
          "id": "433fd8c0-3ad4-4a47-bb63-07760fb5fc3b",
          "bound_box": [343, 3, 496, 154],
          "prob": 0.7158277630805969,
          "area": 0.025435764867531005,
          "expand_by_bound_box": [328, 0, 511, 169],
          "Top Category": "Accessories",
          "Category": "Accessories/Mirrors & Frames",
          "_tags": {
            "Category": [
              {
                "id": "27dd7b55-78c4-45a2-8721-22e93d69f1c3",
                "name": "Accessories/Mirrors & Frames",
                "prob": 1.0
              }
            ],
            "Subcategory": [
              {
                "prob": 0.72697,
                "name": "frame",
                "id": "4851d369-1d77-4d69-9f0d-f3ea107d9307"
              }
            ],
            "Material": [
              {
                "prob": 0.96967,
                "name": "Accessories/Textile",
                "id": "a3ae94de-ea36-4851-b558-76e80cb626b2"
              }
            ],
            "Shape": [
              {
                "prob": 0.91281,
                "name": "square",
                "id": "6d6d96c5-0dc1-4b69-b606-a62cb605d99c"
              }
            ],
            "Top Category": [
              {
                "id": "7c042069-8e9e-4905-82c2-90ca5882ecab",
                "name": "Accessories",
                "prob": 1.0
              }
            ]
          },
          "_tags_map": {
            "Top Category": "Accessories",
            "Category": "Accessories/Mirrors & Frames",
            "Subcategory": "frame",
            "Material": "Accessories/Textile",
            "Shape": "square"
          },
          "_tags_simple": [
            "Accessories",
            "square",
            "frame",
            "Accessories/Textile",
            "Accessories/Mirrors & Frames"
          ]
        }
      ]
    }
  ],
  "status": {
    "code": 200,
    "text": "OK",
    "request_id": "3ada7775-a2f7-4577-8109-8f3111140e2b",
    "proc_id": "f6b2b598-feb2-4c5b-8541-f90cef96069f"
  },
  "statistics": {
    "processing time": 0.8162112236022949
  }
}

POST/v2/tags

Tagging

Quickstart

Given a list of image records, this method returns tags predicted by the Home Decor Tagging service, along with confidence scores for each tag. It is best suited for single-product images.

For multiple images of the same product, set 'aggregate_labels': true to combine tags across the batch. Aggregated results appear in _aggregation and _aggregation_simple.

Required attributes

Name
records
Type
dict
Max
Maximum:10
Description
A batch of JSON records (max 10). Each record represents a single image, defined by _url or _base64.

Optional attributes

Name
aggregate_labels
Type
boolean
Default
Default:false
Description
If true, the records are treated as multiple photos of the same object. Tags are generated for each image separately, then aggregated into a single list for the entire batch.
Name
profile
Type
string
Description
If you have a custom tagging profile, apply its ID to transform the _tags — e.g., rename, add, or remove tags/features.
Name
language
Type
string
Description
Language code for tag translations. For more info, please contact us at care@ximilar.com.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The response body is a JSON object (map) with the following fields:

Name
records
Type
dict
Description
JSON array with the input records, each record enriched by fields _tags and category.
Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).
Name
_aggregation
Type
dict
Description
If aggregate_labels is set to true, this field contains aggregated tags for the entire batch.
Name
_aggregation_simple
Type
dict
Description
If aggregate_labels is set to true, this field contains simplified aggregated tags for the entire batch.

Request

POST

/v2/tags

curl https://api.ximilar.com/tagging/homedecor/v2/tags -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
  "records": [
    { "_url": "https://bit.ly/2IymQJv" },
    {"_base64": "/9j/4AAQSkZJR...", "_id": "image_id"}
  ]
}'

Response

{
  "records": [
    {
      "_url": "https://vize-images.s3.amazonaws.com/image/773e2ab1-2a0c-4524-9593-7395994faae1/46e875e4-e90e-4afa-aa4d-23b320ec6d7c.jpg",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "a24bc3ee-bbe2-40ff-b8a0-edeeb7d720c3"
      },
      "_width": 1000,
      "_height": 1000,
      "Top Category": "Furniture",
      "Category": "Furniture/Sitting",
      "_tags": {
        "Category": [
          {
            "prob": 0.99709,
            "name": "Furniture/Sitting",
            "id": "c397d929-5e29-4722-a98a-13629ae65677"
          }
        ],
        "Subcategory": [
          {
            "prob": 0.96032,
            "name": "Dining chair",
            "id": "1ab17573-78c2-4ccf-840e-93df756a5193"
          }
        ],
        "Top Category": [
          {
            "prob": 0.99406,
            "name": "Furniture",
            "id": "ff06c568-dd14-4fb7-9eae-1a0d3c1da115"
          }
        ]
      },
      "_tags_map": {
        "Top Category": "Furniture",
        "Category": "Furniture/Sitting",
        "Subcategory": "Dining chair"
      },
      "_tags_simple": [
        "Furniture",
        "Dining chair",
        "Furniture/Sitting"
      ]
    }
  ],
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "processing time": 0.8858194351196289
  }
}

POST/v2/detect

Home Decor Detection

Given a list of image records, this method returns detected home decor items and furniture on images with their categories.

Required attributes

Name
records
Type
dict
Max
Maximum:10
Description
A batch of JSON records (max 10). Each record represents a single image, defined by _url or _base64.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The response body is a JSON object (map) with the following fields:

Name
records
Type
dict
Description
JSON array with the input records, each record enriched by field _objects.
Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).

Request

POST

/v2/detect

curl https://api.ximilar.com/tagging/homedecor/v2/detect -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
  "records": [
    { "_url": "https://bit.ly/2IymQJv" },
    {"_base64": "/9j/4AAQSkZJR...", "_id": "image_id"}
  ]
}'

Response

{
  "records": [
    {
      "_url": "https://images.ximilar.com/examples/homedecor/8.jpg",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "86ca41c7-b760-48c1-84df-5f59a21cd5d6"
      },
      "_id": "ee920142-edb5-4545-a9f4-41a3e0397932",
      "_width": 300,
      "_height": 300,
      "_objects": [
        {
          "name": "Textile accessories",
          "id": "02240abc-a136-4230-8fea-f0054ab8eac3",
          "bound_box": [0, 67, 283, 287],
          "prob": 0.5390826463699341,
          "area": 0.6917777777777778,
          "expand_by_bound_box": [0, 45, 299, 299],
          "Top Category": "Accessories",
          "Category": "Accessories/Textile"
        },
        {
          "name": "Relax",
          "id": "5bc71c4e-edc2-4216-a9d5-9a45ec00ea0a",
          "bound_box": [224, 20, 300, 211],
          "prob": 0.4882190525531769,
          "area": 0.1612888888888889,
          "expand_by_bound_box": [217, 1, 299, 230],
          "Top Category": "Furniture",
          "Category": "Furniture/Relax"
        }
      ]
    }
  ],
  "status": {
    "code": 200,
    "text": "OK",
    "request_id": "86ca41c7-b760-48c1-84df-5f59a21cd5d6",
    "proc_id": "8b776662-7987-4b41-b0ca-4154bef2e842"
  },
  "statistics": {
    "processing time": 0.1509261131286621
  }
}