Navbar
shell python
API Documentation

Introduction

The Thread Genius API offers visual style recognition as a service. Use it to tag photos with stylistic concepts, find shoppable products within photos, perform visual search on social media images, or manage and search against your own photos.

Client Libraries / SDKs

Currently we have client libraries available for the following languages:

Authentication

Example authentication:

curl "https://api.threadgenius.com/v1/catalog" \
  -u "API_KEY:"

# curl uses the -u flag to pass basic auth credentials (adding a colon after your API key prevents cURL from asking for a password).
from threadgenius import ThreadGenius
tg = ThreadGenius(api_key='API_KEY')

If you haven’t already, please create a Thread Genius account here

You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

Image Inputs

We define inputs into the Thread Genius API via JSON-formatted strings.

Image Input from URL

Example JSON input:

{
  "image": {
    "url": "https://cdn.example.com/image1.jpeg",
    "crop": [0.1, 0.15, 0.5, 0.8]
  }
}

Attributes

Attribute Type Description
url string The URL of the image
crop (optional) list(float), default [0,0,1,1] A list of floats denoting the percentage crop of the image in order of x1, y1, x2, y2

Example usage:

curl "https://api.threadgenius.co/v1/prediction/tag" \
  -H "Content-Type: application/json" \
  -X POST \
  -u "API_KEY:" \
  -d '{
    "image": {
      "url": "https://cdn.example.com/image.jpeg",
    }
  }'
from threadgenius.types import ImageUrlInput
image = ImageUrlInput(url="https://cdn.example.com/image1.jpeg")

Image Input from Local File

Example JSON input:

{
  "image": {
    "base64": "/9j/4AAQSkZJRgABAQAASABIAAD/...",
    "crop": [0.1, 0.15, 0.5, 0.8]
  }
}

Images inputted from local files are stored and hosted on Thread Genius servers. Response objects will contain the image URLs of the hosted input images.

Attributes

Attribute Type Description
base64 string The base-64 representation of the image
crop (optional) list(float), default [0,0,1,1] A list of floats denoting the percentage crop of the image in order of x1, y1, x2, y2

Example usage:

curl "https://api.threadgenius.co/v1/prediction/tag" \
  -H "Content-Type: application/json" \
  -X POST \
  -u "API_KEY:" \
  -d '{
    "image": {
      "base64": "/9j/4AAQSkZJRgABAQAASABIAAD/..."
    }
  }'
from threadgenius.types import ImageFileInput
image = ImageFileInput(file_object=open('/path/to/image.jpeg'))

Image Cropping

Image inputs have an optional crop parameter. You can use this parameter to specify where the image needs cropping before being processed for predictions or catalog indexing.

Crops are specified as a list of floats. For example [0.1, 0.2, 0.6, 0.7] means the cropped image will have a left edge that starts 10% from the original left edge, a top edge that starts 20% down from the original top edge, a right edge that starts 60% from the original left edge, and a bottom edge that starts 70% from the original top edge.

Catalog API

Use the catalog API to create and manage searchable catalogs of objects. Objects represent any item indexable by an associated image – e.g. blog posts, product SKUs, even users you’d want to segment by taste.

Catalogs

A catalog is a collection of objects, each associated with an image and metadata. Adding objects into a catalog allows you to search them via keyword or image search.

Example JSON object:

{
  "catalog": {
    "status": {
      "code": 0,
      "description": "OK"
    },
    "gid": "catalog_4163ec6d6cc2cc6819e72efc6e3d38",
    "name": "Streetwear Fall 2018",
    "numObjects": 1563,
    "dateCreated": "2017-01-08 16:55:33"
  }
}

Attributes

Attribute Type Description
gid string An id assigned to the catalog
name string A name you provide for the catalog on creation
numObjects integer The total number of catalog objects in the catalog
status Status The catalog status
dateCreated datetime The UTC datetime the catalog was created

Status Codes

Code Description
0 Catalog is ready to be queried.
1 Catalog is currently indexing. Searches can not be made yet.
2 Catalog is deleted.

Create a new catalog

Use this endpoint to create a new empty catalog.

Input JSON-schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    }
  },
  "required": ["name"]
}

Example Request:

curl "https://api.threadgenius.co/v1/catalog" \
  -H "Content-Type: application/json" \
  -X POST \
  -u "API_KEY:" \
  -d '{
    "name": "Streetwear Fall 2018"
  }'
from threadgenius import ThreadGenius

tg = ThreadGenius(api_key="API_KEY")
tg.create_catalog(catalog_name="Streetwear Fall 2018")

Example Response:

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "catalog": {
      "status": {
        "code": 0,
        "description": "OK"
      },
      "gid": "catalog_4163ec6d6cc2cc6819e72efc6e3d38",
      "name": "Streetwear Fall 2018",
      "numObjects": 0,
      "dateCreated": "2017-01-01 16:55:32.425516"
    }
  }
}

HTTP Request

POST https://api.threadgenius.co/v1/catalog

List all catalogs

Use this endpoint to list all catalogs.

Example Request:

curl "https://api.threadgenius.co/v1/catalog" \
  -H "Content-Type: application/json" \
  -X GET \
  -u "API_KEY:" \
from threadgenius import ThreadGenius

tg = ThreadGenius(api_key="API_KEY")
tg.list_all_catalogs()

Example Response:

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "catalogs": [
      {
        "status": {
          "code": 0,
          "description": "OK"
        },
        "gid": "catalog_82859e3723a3de9e069c7f6785d6ea",
        "name": "Catalog 1",
        "numObjects": 150,
        "dateCreated": "2017-01-04 18:07:11"
      },
      {
        "status": {
          "code": 0,
          "description": "OK"
        },
        "gid": "catalog_720dc43e14a97d323e43412932b675",
        "name": "Catalog 2",
        "numObjects": 800,
        "dateCreated": "2017-01-05 11:08:12"
      }
    ]
  }
}

HTTP Request

GET https://api.threadgenius.co/v1/catalog

Get a catalog

Use this endpoint to get a specific catalog.

Example Request:

curl "https://api.threadgenius.co/v1/catalog/catalog_4163ec6d6cc2cc6819e72efc6e3d38" \
  -H "Content-Type: application/json" \
  -X GET \
  -u "API_KEY:" \
from threadgenius import ThreadGenius

tg = ThreadGenius(api_key="API_KEY")
tg.get_catalog('catalog_4163ec6d6cc2cc6819e72efc6e3d38')

Example Response:

  {
    "status": {
      "code": 1000,
      "description": "OK"
    },
    "response": {
      "catalog": {
        "status": {
          "code": 0,
          "description": "OK"
        },
        "gid": "catalog_4163ec6d6cc2cc6819e72efc6e3d38",
        "name": "Streetwear Fall 2018",
        "numObjects": 0,
        "dateCreated": "2017-01-01 16:55:33"
      }
    }
  }

HTTP Request

GET https://api.threadgenius.co/v1/catalog/<gid>

Delete a catalog

Use this endpoint to delete a specific catalog.

curl "https://api.threadgenius.co/v1/catalog/catalog_4163ec6d6cc2cc6819e72efc6e3d38" \
  -H "Content-Type: application/json" \
  -X DELETE \
  -u "API_KEY:" \

Example Response:

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "catalog": {
      "status": {
        "code": 2,
        "description": "Deleted"
      },
      "gid": "catalog_4163ec6d6cc2cc6819e72efc6e3d38",
      "name": "Streetwear Fall 2018",
      "numObjects": 0,
      "dateCreated": "2017-01-01 16:55:33"
    }
  }
}

HTTP Request

DELETE https://api.threadgenius.co/v1/catalog/<catalog_gid>

Objects

A catalog object comprises of an image URL and additional metadata (optional).

Example JSON object:

{
  "object": {
    "status": {
      "code": 0,
      "description": "Success"
    },
    "gid": "object_4163ec6d6cc2cc6819e72efc6e3d38",
    "image": {
      "url": "http://cdn.example.com/image1.jpeg",
      "crop": [0.1, 0.1, 0.9, 0.9]
    },
    "metadata": {
      "brand": "gucci",
      "hashtags": ["bad", "bougie"]
    },
    "dateCreated": "2017-01-08 16:55:33"
  }
}

Attributes

Attribute Type Description
gid string An id assigned to the object
image Image An image associated with the object
status Status The object status
metadata (optional) JSON-object Additional JSON-formatted metadata associated with the object
dateCreated datetime The UTC datetime the object was created

Status Codes

Code Description
0 Object indexed in catalog successfully.
1 Object is currently being indexed.
2 Object is deleted.
3 There was an error indexing this object

Metadata

Catalog objects have an optional metadata parameter. You can use this parameter to attach key-value data to objects.

Metadata is useful for storing additional, structured information about an object. As an example, you could store an object’s unique identifier in your system. Metadata is not used by Thread Genius (e.g., to affect how the indexing is done).

Add objects to a catalog

Use this endpoint to add a list of objects to a specific catalog. Objects are added and indexed asynchronously. To check on the status of an object, see Get an object in a catalog.

Input JSON-schema:

{
  "type": "object",
  "properties": {
    "objects": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "image": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "crop": {
                "type": "array",
                "items": {
                  "type": "float"
                }
              }
            },
            "required": ["url"]
          },
          "metadata": {
            "type": "object"
          } 
        }
      }
    }
  },
  "required": ["objects"]
}

Example Request:

curl "https://api.threadgenius.co/v1/catalog/catalog_4163ec6d6cc2cc6819e72efc6e3d38" \
  -H "Content-Type: application/json" \
  -X POST \
  -u "API_KEY:" \
  -d '{
    "objects": [
        "image": {
          "url": "https://cdn.example.com/image.jpeg"
        },
        "metadata": {
          "brand": "gucci",
          "hashtags": ["bad", "bougie"]
        }
      }
    ]'
from threadgenius import ThreadGenius
from threadgenius.types import CatalogObject, ImageUrlInput

tg = ThreadGenius(api_key="API_KEY")
image = ImageUrlInput(url="https://cdn.example.com/image.jpeg")
metadata = {
  "brand": "gucci",
  "hashtags": ["bad", "bougie"]
}

catalog_object = CatalogObject(
  image_url_input=image,
  metadata=metadata
  )

tg.add_catalog_objects(
  catalog_gid='catalog_4163ec6d6cc2cc6819e72efc6e3d38',
  objects=[catalog_object]
  )

Example Response:

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "objects": [
      {
        "status": {
          "code": 1,
          "description": "Indexing"
        },
        "image": {
          "url": "https://cdn.example.com/image.jpeg",
          "crop": null
        },
        "metadata": {
          "brand": "gucci",
          "hashtags": ["bad", "bougie"]
        },
        "gid": "object_50988696f43e2dfb4e0619b7f666fd",
        "dateCreated": "2017-09-25 18:09:19.080018"
      }
    ]
  }
}

HTTP Request

POST https://api.threadgenius.co/v1/catalog/<catalog_gid>/object

Usage Limitations

Usage type Limit
Image input Image URLs only
Input batch size Up to 32 images in a single request

Get an object from a catalog

Use this endpoint to get information about a specific object from a catalog.

Example Request:

curl "https://api.threadgenius.co/v1/catalog/catalog_4163ec6d6cc2cc6819e72efc6e3d38/object/object_50988696f43e2dfb4e0619b7f666fd" \
  -H "Content-Type: application/json" \
  -X GET \
  -u "API_KEY:" \
from threadgenius import ThreadGenius
from threadgenius.types import CatalogObject, ImageUrlInput

tg = ThreadGenius(api_key="API_KEY")

response = tg.get_catalog_object(
  catalog_gid='catalog_4163ec6d6cc2cc6819e72efc6e3d38',
  object_gid='object_50988696f43e2dfb4e0619b7f666fd'
  )

Example Response:

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "object": {
        "status": {
          "code": 0,
          "description": "Success"
        },
        "image": {
          "url": "https://cdn.example.com/image.jpeg",
          "crop": null
        },
        "metadata": {
          "brand": "gucci",
          "hashtags": ["bad", "bougie"]
        },
        "gid": "object_50988696f43e2dfb4e0619b7f666fd",
        "dateCreated": "2017-09-25 18:09:19.080018"
    }
  }
}

HTTP Request

GET https://api.threadgenius.co/v1/catalog/<catalog_gid>/object/<object_gid>

Delete an object from a catalog

Use this endpoint to delete a specific object from a catalog.

Example Request:

curl "https://api.threadgenius.co/v1/catalog/catalog_4163ec6d6cc2cc6819e72efc6e3d38/object/object_50988696f43e2dfb4e0619b7f666fd" \
  -H "Content-Type: application/json" \
  -X DELETE \
  -u "API_KEY:" \
from threadgenius import ThreadGenius
from threadgenius.types import CatalogObject, ImageUrlInput

tg = ThreadGenius(api_key="API_KEY")

response = tg.delete_catalog_object(
  catalog_gid='catalog_4163ec6d6cc2cc6819e72efc6e3d38',
  object_gid='object_50988696f43e2dfb4e0619b7f666fd'
  )

Example Response:

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "object": {
        "status": {
          "code": 2,
          "description": "Deleted"
        },
        "image": {
          "url": "https://cdn.example.com/image.jpeg",
          "crop": null
        },
        "metadata": {
          "brand": "gucci",
          "hashtags": ["bad", "bougie"]
        },
        "gid": "object_50988696f43e2dfb4e0619b7f666fd",
        "dateCreated": "2017-09-25 18:09:19.080018"
    }
  }
}

HTTP Request

DELETE https://api.threadgenius.co/v1/catalog/<catalog_gid>/object/<object_gid>

List all objects in a catalog

Use this endpoint to page through all objects within a catalog.

Example Request:

curl "https://api.threadgenius.co/v1/catalog/catalog_4163ec6d6cc2cc6819e72efc6e3d38/object" \
  -H "Content-Type: application/json" \
  -X GET \
  -u "API_KEY:" \
from threadgenius import ThreadGenius
from threadgenius.types import CatalogObject, ImageUrlInput

tg = ThreadGenius(api_key="API_KEY")

response = tg.list_all_catalog_objects(
  catalog_gid='catalog_4163ec6d6cc2cc6819e72efc6e3d38'
  )

Example Response:

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "objects": [
      {
        "status": {
          "code": 0,
          "description": "Success"
        },
        "image": {
          "url": "https://cdn.example.com/image1.jpeg",
          "crop": [0, 0, 0.8, 0.8]
        },
        "gid": "object_fa351a707aa2626f562851382c672b",
        "dateCreated": "2017-09-07 22:44:53"
      },
      {
        "status": {
          "code": 0,
          "description": "Success"
        },
        "image": {
          "url": "https://cdn.example.com/image2.jpeg",
          "crop": null
        },
        "gid": "object_fa34de5efdba55198f21a1fec961f1",
        "dateCreated": "2017-09-07 22:45:13"
      }
    ],
    "nextKey": "object_fa34de5efdba55198f21a1fec961f1.catalog_4163ec6d6cc2cc6819e72efc6e3d38"
  }
}

HTTP Request

GET https://api.threadgenius.co/v1/catalog/<catalog_gid>/object

Parameter Description
next_key (optional) Key to get the next page of results

Public Catalogs

We offer the following public catalogs available to be queried by anyone.

Catalog gid Num. Objects (approx.) Description
shopstyle 2,000,000 Products currently sold on ShopStyle
bloglovin_fashion 1,000,000 Fashion-related posts on Bloglovin’ from last 100 days

ShopStyle Products

ShopStyle aggregates millions of products across apparel, accessories, and beauty. We continually index their most up-to-date catalog of products so that you can search them via image query or predicted tags.

Metadata Attributes

Attribute Type Description
price float Listed price for the product SKU
extId string ShopStyle product id
extUrl string URL to the ShopStyle product page
title string Name of product
brand string Brand of product
retailer string Name of the product retailer
gender string Gender of the product
currency string Currency of the listed price
mainImageUrl string URL to the Shopstyle product’s main image
thumbnailUrl string URL to the Shopstyle product’s thumbnail image

Bloglovin’ Fashion Posts

Bloglovin’ aggregates blogger photos from close to a hundred thousand bloggers from around the world. We continually index this content so that you can search them via image query or predicted tags.

Metadata Attributes

Attribute Type Description
extUrl string URL to the Bloglovin’ post
date string UTC date the Bloglovin’ post was created
title string Title of the Bloglovin’ post
nLikes integer Number of likes received on Bloglovin’
blogger object Information about the blogger who wrote the post
blog object Information about the blog this post was posted on

Blogger Attributes

Attribute Type Description
extUrl string URL to the Bloglovin’ blogger profile
avatarImageUrl string URL of the blogger’s avatar
name string Name of the blogger
location string Location of the blogger

Blog Attributes

Attribute Type Description
extUrl string URL to the Bloglovin’ blog
name string Name of the blog
language string Language of blog
nFollowers integer Number of followers on Bloglovin’
social_profiles object Blog’s social media handles
description string Description of blog

Prediction API

Prediction

Thread Genius can predict either tags or bounding boxes around items. Tags are concepts our machine learning model thinks are present within the image input(s). Bounding boxes are drawn around items our model recognizes within the image input(s).

Attributes

Attribute Type Description
gid string An id assigned to the prediction
image Image An image input associated with the prediction
status Status The prediction status
data JSON-object The output of the prediction
dateCreated datetime The UTC datetime the prediction was started

Status Codes

Code Description
0 Prediction has completed successfully.
1 Prediction is still processing.
2 There was an error in making this prediction.

Predict tags for a single image

Example Request:

curl "https://api.threadgenius.co/v1/prediction/tag" \
  -H "Content-Type: application/json" \
  -X POST \
  -u "API_KEY:" \
  -d '{
        "image": {
          "url": "https://cdn.example.com/image.jpeg"
        }
    }'
from threadgenius import ThreadGenius
from threadgenius.types import ImageUrlInput

tg = ThreadGenius(api_key='API_KEY')
image = ImageUrlInput('https://cdn.example.com/image.jpeg')

response = tg.tag_image(image=image)

Example response

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "prediction": {
      "status": {
        "code": 0,
        "description": "Success"
      },
      "image": {
        "url": "'https://cdn.example.com/image.jpeg'",
        "crop": null
      },
      "gid": "tag_9a9a5d159b18a405c9845cfec1ba7d5df645d4249111db13a4bc8f24",
      "data": {
        "tags": [
          {
            "confidence": 0.6654632091522217,
            "type": "fashion>pattern",
            "name": "tattersall"
          },
          {
            "confidence": 0.6165093779563904,
            "type": "fashion>shape",
            "name": "wind jacket"
          },
          {
            "confidence": 0.5376437306404114,
            "type": "fashion>color",
            "name": "color gold"
          },
          {
            "confidence": 0.22115056216716766,
            "type": "fashion>detail",
            "name": "contrast collar"
          },
          {
            "confidence": 0.16744108498096466,
            "type": "fashion>detail",
            "name": "funnel neck zip"
          },
          {
            "confidence": 0.14592541754245758,
            "type": "fashion>color",
            "name": "color military green"
          },
          {
            "confidence": 0.115085169672966,
            "type": "fashion>shape",
            "name": "raincoat"
          },
          {
            "confidence": 0.10775481909513474,
            "type": "fashion>shape",
            "name": "blouson jacket"
          }
        ]
      },
      "dateCreated": "2017-09-26 00:09:30.912580"
    }
  }
}

HTTP Request

POST https://api.threadgenius.co/v1/prediction/tag

Batch predict tags

Use the following endpoint to predict tags for multiple images. Batch predictions are placed on a queue. In the response, you’ll get prediction gids, which are identifiers for checking up on the status of a prediction. Predictions have a TTL of 3 days.

Example Request:

curl "https://api.threadgenius.co/v1/prediction/tag" \
  -H "Content-Type: application/json" \
  -X POST \
  -u "API_KEY:" \
  -d '{
        "images": [
            {
              "url": "https://cdn.example.com/image1.jpeg"
            },
            {
              "url": "https://cdn.example.com/image2.jpeg"
            }
        ]
    }'
from threadgenius import ThreadGenius
from threadgenius.types import ImageUrlInput

tg = ThreadGenius(api_key='API_KEY')

urls = [
    'https://cdn.example.com/image1.jpeg',
    'https://cdn.example.com/image2.jpeg'
]
images = [ImageUrlInput(url) for url in urls]

response = tg.tag_image_urls(images=images)

Example Response

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "predictions": [
      {
        "status": {
          "code": 1,
          "description": "Processing"
        },
        "image": {
          "url": "https://cdn.example.com/image1.jpeg",
          "crop": null
        },
        "gid": "tag_9a7e7ff5bf9e5ef1e63c862c57300f30fe5a4a1388f918f3618a228e",
        "dateCreated": "2017-09-26 00:18:17.179599"
      },
      {
        "status": {
          "code": 1,
          "description": "Processing"
        },
        "image": {
          "url": "https://cdn.example.com/image2.jpeg",
          "crop": null
        },
        "gid": "tag_5ec8069c7323323210c23483defb4cb828c47bfd06e9963bb777fd3a",
        "dateCreated": "2017-09-26 00:18:17.179599"
      }
    ]
  }
}

HTTP Request

POST https://api.threadgenius.co/v1/prediction/tag

Usage Limitations

Usage type Limit
Image input Image URLs only
Input batch size Up to 32 images in a single request

Get a tag prediction

Tag predictions made with more than one image input are placed in a queue to be processed for later. You can check up on the status of these predictions using the following endpoint.

Example Request:

curl "https://api.threadgenius.co/v1/prediction/tag/tag_9a9a5d159b18a405c9845cfec1ba7d5df645d4249111db13a4bc8f24" \
  -H "Content-Type: application/json" \
  -X GET \
  -u "API_KEY:" \
from threadgenius import ThreadGenius
from threadgenius.types import ImageUrlInput

tg = ThreadGenius(api_key='API_KEY')
response = tg.get_tag(tag_gid='tag_9a9a5d159b18a405c9845cfec1ba7d5df645d4249111db13a4bc8f24')

Example Response

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "prediction": {
      "status": {
        "code": 0,
        "description": "Success"
      },
      "image": {
        "url": "'https://cdn.example.com/image.jpeg'",
        "crop": null
      },
      "gid": "tag_9a9a5d159b18a405c9845cfec1ba7d5df645d4249111db13a4bc8f24",
      "data": {
        "tags": [
          {
            "confidence": 0.6654632091522217,
            "type": "fashion>pattern",
            "name": "tattersall"
          },
          {
            "confidence": 0.6165093779563904,
            "type": "fashion>shape",
            "name": "wind jacket"
          },
          {
            "confidence": 0.5376437306404114,
            "type": "fashion>color",
            "name": "color gold"
          },
          {
            "confidence": 0.22115056216716766,
            "type": "fashion>detail",
            "name": "contrast collar"
          },
          {
            "confidence": 0.16744108498096466,
            "type": "fashion>detail",
            "name": "funnel neck zip"
          },
          {
            "confidence": 0.14592541754245758,
            "type": "fashion>color",
            "name": "color military green"
          },
          {
            "confidence": 0.115085169672966,
            "type": "fashion>shape",
            "name": "raincoat"
          },
          {
            "confidence": 0.10775481909513474,
            "type": "fashion>shape",
            "name": "blouson jacket"
          }
        ]
      },
      "dateCreated": "2017-09-26 00:09:30.912580"
    }
  }
}

HTTP Request

GET https://api.threadgenius.co/v1/prediction/tag/<prediction_gid>

List all tag predictions

You can page through all tag predictions from the last 3 days by using the following endpoint.

Example Request:

curl "https://api.threadgenius.co/v1/prediction/tag" \
  -H "Content-Type: application/json" \
  -X GET \
  -u "API_KEY:" \
from threadgenius import ThreadGenius
from threadgenius.types import ImageUrlInput

tg = ThreadGenius(api_key='API_KEY')
response = tg.list_all_tags()

HTTP Request

GET https://api.threadgenius.co/v1/prediction/tag

Parameter Description
next_key (optional) Key to get the next page of results

Detect items within a single image

Use the following endpoint to predict bounding boxes around items of interest within a single image.

Example Request:

curl "https://api.threadgenius.co/v1/prediction/detect" \
  -H "Content-Type: application/json" \
  -X POST \
  -u "API_KEY:" \
  -d '{
        "image": {
          "url": "https://cdn.example.com/image.jpeg"
        }
    }'
from threadgenius import ThreadGenius
from threadgenius.types import ImageUrlInput

tg = ThreadGenius(api_key='API_KEY')
image = ImageUrlInput('http://www.sandipointe.com/im/jackets/kim-kardashian-jacket-7.jpg')

response = tg.detect_image(image=image)

Example Response:

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "prediction": {
      "status": {
        "code": 0,
        "description": "Success"
      },
      "image": {
        "url": "http://www.sandipointe.com/im/jackets/kim-kardashian-jacket-7.jpg",
        "crop": null
      },
      "gid": "detect_f671bf9af625318f824a621fc7d1a1339674ad71a1581253d07a38b6",
      "data": {
        "detections": [
          {
            "category": "pants-long",
            "score": 0.8277020454406738,
            "bbox": [
              0.07961783439490445,
              0.3618181818181818,
              0.8980891719745223,
              0.9327272727272727
            ]
          },
          {
            "category": "footwear-regular",
            "score": 0.9736045598983765,
            "bbox": [
              0.46178343949044587,
              0.8290909090909091,
              0.6847133757961783,
              0.9763636363636363
            ]
          },
          {
            "category": "footwear-regular",
            "score": 0.9582731127738953,
            "bbox": [
              0.2770700636942675,
              0.7727272727272727,
              0.5254777070063694,
              0.9254545454545454
            ]
          },
          {
            "category": "outerwear-light",
            "score": 0.9898208379745483,
            "bbox": [
              0.15605095541401273,
              0.12363636363636364,
              0.7643312101910829,
              0.5218181818181818
            ]
          }
        ],
        "size": [
          314,
          550
        ]
      },
      "dateCreated": "2017-09-26 00:40:14.467458"
    }
  }
}

HTTP Request

POST https://api.threadgenius.co/v1/prediction/detect

Batch detect items

Use the following endpoint to predict bounding boxes around items of interest within multiple images. In the response, you’ll get prediction gids, which are identifiers for checking up on the status of a prediction. Predictions have a TTL of 3 days.

Example Request

curl "https://api.threadgenius.co/v1/prediction/detect" \
  -H "Content-Type: application/json" \
  -X POST \
  -u "API_KEY:" \
  -d '{
        "images": [
            {
              "url": "https://cdn.example.com/image1.jpeg"
            },
            {
              "url": "https://cdn.example.com/image2.jpeg"
            }
        ]
    }'
from threadgenius import ThreadGenius
from threadgenius.types import ImageUrlInput

tg = ThreadGenius(api_key='API_KEY')

urls = [
    'https://cdn.example.com/image1.jpeg',
    'https://cdn.example.com/image2.jpeg'
]
images = [ImageUrlInput(url) for url in urls]

response = tg.detect_image_urls(images=images)

Example Response

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "predictions": [
      {
        "status": {
          "code": 1,
          "description": "Processing"
        },
        "image": {
          "url": "https://cdn.example.com/image1.jpeg",
          "crop": null
        },
        "gid": "detect_855fa11b6b7b6262a20df4baf8ddc0a1d4b7421d82587736dff0ba8f",
        "dateCreated": "2017-09-26 00:36:45.458705"
      },
      {
        "status": {
          "code": 1,
          "description": "Processing"
        },
        "image": {
          "url": "https://cdn.example.com/image2.jpeg",
          "crop": null
        },
        "gid": "detect_9a7e7ff5bf9e5ef1e63c862c57300f30fe5a4a1388f918f3618a228e",
        "dateCreated": "2017-09-26 00:36:45.458705"
      }
    ]
  }
}

HTTP Request

POST https://api.threadgenius.co/v1/prediction/detect

Usage Limitations

Usage type Limit
Image input Image URLs only
Input batch size Up to 5 images in a single request

Get a detect prediction

Detect predictions made with more than one image input are placed in a queue to be processed for later. You can check up on the status of these predictions using the following endpoint.

Example Request:

curl "https://api.threadgenius.co/v1/prediction/detect/detect_6e724f9ae08630a8a47c73655440b4f454d4098eecffa23bd6e8e2f2" \
  -H "Content-Type: application/json" \
  -X GET \
  -u "API_KEY:" \
from threadgenius import ThreadGenius
from threadgenius.types import ImageUrlInput

tg = ThreadGenius(api_key='API_KEY')
response = tg.get_detection(detect_gid='detect_6e724f9ae08630a8a47c73655440b4f454d4098eecffa23bd6e8e2f2')

Example Response:

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "prediction": {
      "status": {
        "code": 1,
        "description": "Processing"
      },
      "image": {
        "url": "http://www.sandipointe.com/im/jackets/kim-kardashian-jacket-7.jpg",
        "crop": null
      },
      "gid": "detect_6e724f9ae08630a8a47c73655440b4f454d4098eecffa23bd6e8e2f2",
      "dateCreated": "2017-09-26 00:40:14.467458"
    }
  }
}

HTTP Request

GET https://api.threadgenius.co/v1/prediction/detect/<prediction_gid>

List all detect predictions

You can page through all detect predictions from the last 3 days by using the following endpoint.

Example Request:

curl "https://api.threadgenius.co/v1/prediction/detect" \
  -H "Content-Type: application/json" \
  -X GET \
  -u "API_KEY:" \
from threadgenius import ThreadGenius
from threadgenius.types import ImageUrlInput

tg = ThreadGenius(api_key='API_KEY')
response = tg.list_all_detections()

HTTP Request

GET https://api.threadgenius.co/v1/prediction/detect

Parameter Description
next_key (optional) Key to get the next page of results

Taxonomy

Fashion

Term Examples
abstract
alice band
aline dress
aline skirt
almond toe
american flag
amethyst
anchor print
ankle boot
anklestrap
argyle
army boots
army jacket
asymmetrical skirt
aviator jacket
aviator sunglasses
aztec kilim
babydoll
backpack
balconette bra
ballerina dress
ballet flat
band jacket
bandage dress
bandeau bikini
bandeau crop top
bangle bracelet
baroquepatterned
barrel handbag
baseball cap
baseball jersey
basketball replica jersey
basketball shorts
basketball sneakers
beaded neck
beaded
beanie cable knit
beanie pom
beanie slouchy
beanie waffle knit
beanie
bell sleeves
belted waist
belt
berber kilim
bermuda shorts
bib necklace
bib shirt
bifold wallet
biker boots
biker jeans
bikini bottoms
bikini
bit loafers
black face watch
blazer singlebutton
blazer
blind eyelets
block heel
blossom print
blouse
blouson dress
blouson jacket
blue face watch
blue soles
blue topaz
boat shoes
boatneck
bodysuit
bolero jacket
bomber hat
bootie
boot
boston satchel
bow collar
bow detailing
bow tie
bowling handbag
box clutch
boxer brief
boyfriend jeans
braided belt
bra
breast pockets
brief trunks
briefcase
brocade
brogue boots
brogue loafers
brogues
brooch
brown leather
bucket bag
bucket hat
buckles
buffalo plaid
burberry house check design
bustier
butterfly print
butterfly shorts
buttonup shirt
cableknit cardigan
cableknit sweater
cabochon
caftan
cage design
camisole
camouflage
cap leather
cap toe
cape coat
capelet coat
capri pants
capsleeve
card holder
cardigan
cargo pockets pants
cateye glasses
cateye sunglasses
chain bracelet
chain link
chain necklace
chain strap
chandelier
checkered
chelsea boots
chelsea collar
chesterfield coat
chevron
chinos
choker necklace
chuck taylor
chukka
cigarette trousers
circle sunglasses
circular frame
cleated
cloth headband
clutch
cocoon coat
coin purse
cold shoulder
color acid green
color anthracite
color azure
color beige
color black leather
color blackgold
color blackwhite
color black
color blocked
color blue
color blush
color bordeaux
color brick red
color bright blue
color bronze
color brown
color camel
color charcoal
color chocolate
color coral
color cream
color dark blue
color dark green
color emerald
color fuchsia
color gold
color green
color grey
color heather grey
color light blue
color light green
color light grey
color light pink
color lilac
color mandarin
color military green
color navy
color nude
color orange
color pink
color platinum
color purple
color red
color rust
color salmon
color sand
color silver
color tan
color turquoise
color white
color yellow
concealed buttonfront closure
cone heel
continental wallet
contrast collar
cork sandals
corset
cosmetics pouch
covered wedge
coverup
cowboy boots
cowl
cracked fabric
crew neck sweater
crewneck
crocembossed
crocheted
crop top
cropped jacket
cropped trousers
cross body bag
crossover straps pumps
crystalembellished
cubic zirconia
cufflinks
culottes
cutaway shoulder
cutouts dress
daisy
dark wash denim
demi cups
denim jacket
denim pants
denim shorts
denim skirt
derby shoes
desert boots
diagonal stripes tie
digital watch
dirndl skirt
disc pendant
dolman sleeves
dorsay flats
dorsay pumps
dot print
doublebreasted
doublebridge
drawcord closure bag
drawstring collar
drawstring pants
drawstring shorts
dress pants
dress shirt
driving gloves
driving loafers
drop waist dress
dropped shoulders
drops earrings
dual handles
duck camo
duck graphic
duffle bag
duffle jacket
elbow patches
embellished collar
emerald earrings
emerald necklace
emerald ring
empire silhouette
envelope clutch
epaulettes
espadrilles slipon
espadrilles wedge
eyelet
faceted earrings
faceted ring
fair isle pattern
fanny pack
feather print
feathers
fedora
field jacket
filigree
fishnet stockings
fitandflare
flap backpack
flared skirt
flat sandals
flats
flex cap
flip flops
floral embroidery
flounce hem
flower
foileffect
frame handbag
fringed ends
fulllength jacket
funnel neck zip
fur boots
fur coat
fur collar
fur scarf
garnet necklace
garnet ring
geo print
gilet
gingham
gladiator sandal
glen plaid
glitter
gloves fingerless
gloves knit
gloves thumb hole
goldplated
gown
gradient lenses
graphic tee
grid check
gum soles
halfzip
halterneck
handbag
harem pants
harness strap
harrington jacket
heart
heelless
henley
high neck
hightop
highwaisted
hilo hem dress
hobo bag
hooded
hoodie
hoop earrings
horizontal stripe
houndstooth
illusion neckline
infinity scarf
intrecciato
iridescent
jade necklace
jeweled accents
jeweled collar
jeweled shoulder
jumper dress
jumpsuit
jute bag
keyhole neckline
kimono
kitten heel
knee length skirt
kneehigh boots
kneelength dress
knife pleat
knit beanie
knit dress
knit sweater
knot detail
knotted crop top
knotted cutout
knotted fringe
lace dress
laceup boots
laceup sandals
lamé
laser cut
leaf earrings
leather backpack
leather bag
leather belt
leather boots
leather bracelet
leather flipflops
leather gloves black
leather loafers
leather pants
leather sandals
leather skirt
leather tote
leather wallet
leather wedge
leathersleeved
led watch
leggings
leopard
link bracelet
loafers
longsleeve dress
longsleeved
louboutin heels
low cut socks
lowtop
mackintosh coat
madras
mandarin collar shirt
marbleprint
mary jane pumps
maxi dress
maxi skirt
medallion pendant
mermaid dress
messenger bag
metal eyelets
midcalf boots
mini dress
miniskirt
mink
missoni
moc toe
moccasin
monk strap
moto jacket
mules
muscle tee
nautical striped
neck tie
notch lapel
numeral
off shoulder
ombre
onepiece swimsuit
oneshoulder style
openfront
opentoe
openwork
optical glasses
oval sunglasses
overalls
overcoat
overtheknee socks
oxfords
padded shoulders
paintsplattered
paisley
pajama
palm tree
panama hat
panelling hi top
panty
parka
patchwork
pave
peacoat
peaked lapel
pearls earrings
pearls necklace
pencil skirt
pendant necklace
penny loafers
peplum
perforated leather
peruvian hat
peter pan collar
pinstriped
pintucked dress
plaid shirt
plaid
platform heel
plunge bandeau dress
plunge neckline dress
pocket sweater
poet sleeves
point collar
pointedtoe
polo
poncho
pouch
press studs
princess coat
printed dress
puffer jacket
pull tab
pumps
pushlock closure bag
pushup bra
pyramid stud
python print
queen ann neckline
quilted jacket
quilted leather
quilting
racer back
raffia
raglan
rain boots
rainbow stripes
raincoat
rectangle shape glasses
rectangular buckle belt
rectangular watch
red soles sneakers
replica jersey hockey
ribbon hat
ribknit
riding boots
ring
ripped jeans
ripped knees
robe
roman numerals
romper
rope
round closedtoe
ruby earrings
ruby necklace
ruby ring
ruched dress
ruffle collar
ruffled
running sneakers
saddle bag
sarong
scalloped topline
scarf
scoop neck
scoopneck tee
scuba top
selftie sash
sequin
shantung
shawl collar
shawl lapel
shawl
shearling jacket
shearling shoes
sheath dress
sheer lace
shield sunglasses
shift dress
shirring
shirt waist dress
shirt with colored pocket
shirtdress
shopper tote
shortsleeved dress
shortsleeved shirt
shortsleeved tshirt
shorts
shrug
sicily bag
skater dress
skinny jeans
skull
sleepshirt
sleeveless dress
sleeveless
slides
sling bag
slingbacks
slip dress
slipon sneakers
slipper
slogan
smock dress
snapback
snow boots
socks
space dye
spaghetti strap
spike
splash print
split back
split neckline
sports bra
sports headband
spread collar
square hoop
square scarf
squared frame
squared neckline
squared toe
stacked heel
stand collar
stars sweater
sterling silver
stiletto
stole
strapless dress
strappy sandals
stripe
stud earrings
studded leather
subdials
suit jacket
surplice neckline
sweater dress
sweatpants
sweatshirt
sweetheart
swim trunks
swing coat
swing dress
tank dress
tankini
tank
tartan
tassel loafers
tassel
tattersall
tbar sandals
teardrop earrings
tent dress
thong sandal
thong
threequartersleeve
tie clip
tiedye
tiered skirt
tigerprint
tights
tinted lenses
tippedcollar
tortoiseshell sunglasses
tote
track jacket
track pants
transparent sunglasses
trapeze bag
trapeze dress
trench coat
triangle bikini
triangle earrings
triangle necklace
tribal
trifold wallet
tropical print
trousers
trumpet skirt
tshirt dress
tube dress
tulip skirt
tulle skirt
tunic
turnlock
turquoise earrings
turquoise necklace
turquoise ring
turtleneck
tuxedo jacket
tuxedo shirt
twisted top
twopiece dress
twopiece sandal
ugg boots
underwear trunks
varsity cardigan
varsity jacket
varsity sweatshirt
vback dress
velcro sandals
velcro sneakers
vertical stripes dress
visor
vneck sweater
vneck tee
vneckline
waistcoat
wallet
watch black leather
watch brown leather
watch plastic bracelet
watch steel bracelet
waterfall collar
wayfarer glasses
wayfarer sunglasses
wedge sandals
wedges
western shirt
white face watch
wide instep strap
wind jacket
wind pants
wing sandals
with patches
wood sunglasses
wooden heel
wool coat
wrap blouse
wrap dress
wristlet strap
yellow sole
zebra print
zigzag pattern
zip boots
zip hoodie
ziparound wallet

Search API

Search Queries

You can search catalogs with either keyword-based queries or image-based queries (i.e. visual search). They’re comprised of either a keywords list or an image, plus an optional parameter n_results specifying the number of results (default is 50). Results come back sorted by relevancy.

Input JSON-schema:

{
    "type": "object",
    "properties": {
        "keywords": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "image": {
            "type": "object",
            "properties": {
                "url": {
                    "type": "string"
                },
                "crop": {
                   "type": "array",
                   "items": {
                     "type": "float"
                   }
                }
            },
            "required": ["url"]
        },
        "n_results": {
            "type": "integer"
        },
        "anyOf": [
            {"required" : ["keywords"]},
            {"required" : ["image"]}
        ]
    }
}

If you don’t have a catalog to search with, you can start with one of our public catalogs.

Search catalog by predicted keywords

Use this endpoint to search a catalog by keywords predicted by our machine learning model.

Example Request:

curl "https://api.threadgenius.co/v1/catalog/catalog_2c8cb9bc45983c2b1e4a5edbdbdebe/search" \
  -H "Content-Type: application/json" \
  -X POST \
  -u "API_KEY:" \
  -d '{
        "keywords": ["camouflage", "jacket"],
        "n_results": 2
    }'
from threadgenius import ThreadGenius

tg = ThreadGenius(api_key='API_KEY')

response = tg.search_by_keywords(
    catalog_gid='catalog_2c8cb9bc45983c2b1e4a5edbdbdebe',
    keywords=['camouflage', 'jacket']
    n_results=2
    )

Example response

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "results": [
      {
        "score": 1,
        "object": {
          "status": {
            "code": 0,
            "description": "Success"
          },
          "image": {
            "url": "https://img.shopstyle-cdn.com/pim/8b/54/8b54c0190adbb561ba451c6244033f63_best.jpg",
            "crop": null
          },
          "gid": "object_deafc0791ed7f664b536ea855f0910",
          "dateCreated": "2017-09-26 08:57:52.705937"
        }
      },
      {
        "score": 0.9991402841061937,
        "object": {
          "status": {
            "code": 0,
            "description": "Success"
          },
          "image": {
            "url": "https://img.shopstyle-cdn.com/pim/e7/79/e779d180ea1953a667607c457cd8b08e_best.jpg",
            "crop": null
          },
          "gid": "object_49b8beba585eb10ce916ed3e9e73af",
          "dateCreated": "2017-09-26 08:57:52.705889"
        }
      }
    ]
  }
}

HTTP Request

POST https://api.threadgenius.co/v1/catalog/<catalog_gid>/search

Usage Limitations

Usage type Limit
Number of keywords Up to 5

Search catalog by image

Use this endpoint to perform a visual search over a catalog.

Example Request:

curl "https://api.threadgenius.co/v1/catalog/catalog_2c8cb9bc45983c2b1e4a5edbdbdebe/search" \
  -H "Content-Type: application/json" \
  -X POST \
  -u "API_KEY:" \
  -d '{
        "image": {
            "url": "https://cdn.shopify.com/s/files/1/1223/5758/products/chelsea-blk-01_2048x2048.jpg"
        },
        "n_results": 2
    }'
from threadgenius import ThreadGenius
from threadgenius.types import ImageUrlInput

tg = ThreadGenius(api_key='API_KEY')
image = ImageUrlInput(url='https://cdn.shopify.com/s/files/1/1223/5758/products/chelsea-blk-01_2048x2048.jpg')

tg.search_by_image(
    catalog_gid='catalog_2c8cb9bc45983c2b1e4a5edbdbdebe',
    image=image,
    n_results=2
    )

Example response

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "results": [
      {
        "score": 0.7605573087930679,
        "object": {
          "status": {
            "code": 0,
            "description": "Success"
          },
          "image": {
            "url": "https://img.shopstyle-cdn.com/pim/cf/46/cf462ec91c099c6fa7c18b67d03e8f62_best.jpg",
            "crop": null
          },
          "gid": "object_b79d79379afb86e924dd16de2d4c2e",
          "dateCreated": "2017-09-26 09:36:29.088696"
        }
      },
      {
        "score": 0.755596935749054,
        "object": {
          "status": {
            "code": 0,
            "description": "Success"
          },
          "image": {
            "url": "https://img.shopstyle-cdn.com/pim/1b/8b/1b8b7e8171852e767d27cf23f6b5bf49_best.jpg",
            "crop": null
          },
          "gid": "object_46e2afa2bf737caf627bbbabd12c63",
          "dateCreated": "2017-09-26 09:36:29.088744"
        }
      }
    ]
  }
}

HTTP Request

POST https://api.threadgenius.co/v1/catalog/<catalog_gid>/search

Usage Summary

Use this endpoint to get your historical usage summary. Summaries are keyed by the month-year in which the API requests were made.

Only successful requests get counted (e.g. catalog objects that failed to index don’t get logged in your usage summary).

Example Request

curl "https://api.threadgenius.co/v1/usage" \
  -H "Content-Type: application/json" \
  -X GET \
  -u "API_KEY:" \
from threadgenius import ThreadGenius

tg = ThreadGenius(api_key='API_KEY')
response = tg.get_usage_summary()

Example Response

{
  "status": {
    "code": 1000,
    "description": "OK"
  },
  "response": {
    "usage": {
      "9-2017": {
        "activeCatalogObjects": 51,
        "detect": 3,
        "createCatalog": 17,
        "searchByImage": 1,
        "addCatalogObject": 51,
        "tag": 62,
        "deleteCatalogObject": 7,
        "searchByKeyword": 2,
        "deleteCatalog": 6
      }
    }
  }
}

HTTP Request

GET https://api.threadgenius.co/v1/usage

Summary Types

Summary Type Description
activeCatalogObjects Number of indexed objects actively sitting in catalogs
detect Number of images detected
createCatalog Number of catalogs created
searchByImage Number of searches made by image query
addCatalogObject Number of catalog objects added and indexed
tag Number of images tagged
deleteCatalogObject Number of catalog objects deleted
searchByKeyword Number of searches made by keyword query
deleteCatalog Number of catalogs deleted

Error Codes

The Thread Genius API uses the following error codes for response statuses.

Code Meaning
1000 Request succeeded
1001 Input needs to be JSON-formatted
1002 Request body was too large (Max 5MB)
2001 Crop requires four points
2002 Crop points must be percentage values between 0 and 1
2003 Crop points [x1,y1,x2,y2] must satisfy x1 < x2 and y1 < y2
2004 Need an image URL
2005 Could not parse image file
2006 Image too large (Max 2MB)
2007 No image(s) provided
2008 Error downloading image from url. Took too long to download.
2009 Error downloading image from url. Image file size limit (2MB) exceeded.
2010 Bad image URL input
2011 Too many images in request (Max 32)
2012 Too many keywords in query (Max 10)
2013 Need to provide query to search with
3000 Catalog already deleted
3001 Catalog not found
3002 Catalog object not formatted correctly
3003 Too many objects to add at once (Max 32)
3005 Object does not have valid JSON-formatted metadata
3006 Object does not have a valid URL
3008 Catalog object not found
3009 No catalog name provided
3010 No read access to catalog.
3011 No write access to catalog.
3012 Catalog indexing in progress
3013 Invalid next key for catalog objects
4001 Invalid next key for predictions
4002 Invalid prediction gid