POST add

Index and add an image to your collection. This method is used to populate your image collection.

Resource URL

https://multicolorengine.tineye.com/<company>/rest/add/

Performance

The MulticolorEngine API can perform one add, delete, or update operation at a time. Any extra requests submitted will be queued up for processing as slots become available.

For maximum performance images should be pre-scaled, as described under Image Limitations below. Thus, in some cases where you could use URLs, it may be better to do the download yourself, scale the image, and send it in the request. If you are using URLs, make sure that the image comes from a low latency server as the API will need to download them before indexing.

Image limitations

  • Naming conflicts: When images are uploaded to the service, the same path is used to store it. Uploading an image with the same file path will result in the existing image being overwritten. This helps avoid duplicate entries.
  • Image size: For optimal performance, uploaded images should be 200px in size in the smallest dimension. For example, 600x400 pixels is larger than required and it will take longer to transfer this file to your MulticolorEngine server. It would be faster to resize this image to be 300x200 and then send it. Smaller images may work, and need not be scaled up.
  • Image format: Accepted formats are JPEG, PNG, GIF (non-animated), BMP, and TIFF files.

Metadata limitations

The metadata keywords can contain any character. However, some characters need to be escaped when using the JSON or XML protocol (see the Character escaping and Handling Unicode sections under Metadata format).

Parameters

Images

In addition to the Common parameters there are:

Key Description
image An image file object that will be added to the collection.
filepath (optional) A filepath under which the first image file will be added to the collection. If not supplied, the API will use the name as specified in the filename parameter of a multipart HTTP request.

URLs

In addition to the Common parameters there are:

Key Description
url A URL of the image file that will be added to the collection.
filepath A filepath under which the first image file will be added to the collection.

For Images or URLs

ignore_background (optional) Whether to detect and ignore the background region of the image files, can be either true or false, defaults to true.
ignore_interior_background (optional) Whether to detect and ignore regions that have the same color as the background region but are surrounded by one or more non background regions, can be either true or false, defaults to true.
metadata A hierarchical set of keywords to be stored along with the image. Can be sent using either XML or JSON format.

Request example

Images (with keyword metadata)

curl https://multicolorengine.tineye.com/<company>/rest/add/       \
     -F "image=@1.jpg;filename=path/folder/1.jpg"                  \
     -F "metadata='{\"keywords\": [\"dolphin\", \"shark\", \"whale\"], \"id\": {\"action\": \"return\", \"type\": \"uint\", \"\": \"67890\"}}'"

URLs

curl https://multicolorengine.tineye.com/<company>/rest/add/       \
     -F "url=http://example.com/1.jpg"                             \
     -F "filepath=path/folder/1.jpg"                               \
     -F "ignore_background=true"                                   \
     -F "ignore_interior_background=false"

Response example

JSON

{
    "status": "ok",
    "error": [],
    "method": "add",
    "result": []
}

XML

<?xml version="1.0" encoding="utf-8"?>
<data>
    <error/>
    <method>add</method>
    <result/>
    <status>ok</status>
</data>