PUT update¶
Add an image to your collection or update an existing image. This method is used to populate your image collection. Images can be uploaded directly to the server or a URL where the image is located can be specified.
Resource URL¶
https://multicolorengine.tineye.com/<company>/rest/update/
Performance¶
The MulticolorEngine API can perform one add, update or delete request at a time. Any extra requests submitted will be queued up for processing as slots become available.
Each request accepts maximum 10 images or URLs.
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: 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 600px in size in the smallest dimension. For example, 1200x800 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 900x600 and then send it. Images smaller than 600px may provide acceptable results, if you don’t have access to higher resolution versions. Do not scale up images.
Image format: Accepted formats are JPEG, PNG, WEBP, AVIF, GIF, BMP and TIFF files. Animated images are not supported.
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¶
In addition to the Common parameters there are:
Image¶
Key |
Description |
|---|---|
image |
An image file object that will be updated or added to the collection. |
image_id (optional) |
An ID under which the image file will be updated or added to the collection. Any string or integer can be used as image ID, up to 255 characters. |
filepath (optional) |
A filepath under which the image file will be updated or added to the collection. If not supplied, the API will use the name as specified in the filename parameter of a multipart HTTP request. |
metadata (optional) |
A hierarchical set of keywords to be stored along with the image. Can be sent using either XML or JSON format. |
Images¶
Key |
Description |
|---|---|
images[0] |
The first image file object that will be updated or added to the collection. |
image_ids[0] (optional) |
An ID under which the first image file will be updated or added to the collection. |
filepaths[0] (optional) |
A filepath under which the first image file will be updated or added to the collection. |
metadata[0] (optional) |
A hierarchical set of keywords to be stored along with the first image. |
… |
… |
images[n] (optional) |
The last image file object that will be updated or added to the collection. |
image_ids[n] (optional) |
An ID under which the last image file will be updated or added to the collection. |
filepaths[n] (optional) |
A filepath under which the last image file will be updated or added to the collection. |
metadata[n] (optional) |
A hierarchical set of keywords to be stored along with the last image. |
URL¶
Note that each url must have a filepath.
Key |
Description |
|---|---|
url |
The URL of an image file that will be updated or added to the collection. |
image_id (optional) |
An ID under which the image file will be updated or added to the collection. Any string or integer can be used as image ID, up to 255 characters. |
filepath |
A filepath under which the image file will be updated or added to the collection. |
metadata (optional) |
A hierarchical set of keywords to be stored along with the image. Can be sent using either XML or JSON format. |
URLs¶
Key |
Description |
|---|---|
urls[0] |
The URL of the first image file that will be updated or added to the collection. |
image_ids[0] (optional) |
An ID under which the first image file will be updated or added to the collection. |
filepaths[0] (optional) |
A filepath under which the first image file will be updated or added to the collection. |
metadata[0] (optional) |
A hierarchical set of keywords to be stored along with the first image. |
… |
… |
urls[n] (optional) |
The URL of the last image file that will be updated or added to the collection. |
image_ids[n] (optional) |
An ID under which the last image file will be updated or added to the collection. |
filepaths[n] (optional) |
A filepath under which the last image file will be updated or added to the collection. |
metadata[n] (optional) |
A hierarchical set of keywords to be stored along with the last image. |
For Images and URLs¶
ignore_background (optional) |
Whether to detect and ignore the background region of the image files, can be either true or false, defaults to false. |
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 false. |
Request examples¶
Images (with keyword metadata)¶
curl -X PUT https://multicolorengine.tineye.com/<company>/rest/update/ \
-F "image=@1.jpg;filename=path/folder/1.jpg" \
-F "image_id=8ae4 ce20 88b05f" \
-F "metadata='{\"keywords\": [\"dolphin\", \"shark\", \"whale\"], \"id\": {\"action\": \"return\", \"type\": \"uint\", \"\": \"67890\"}}'"
or
curl -X PUT https://multicolorengine.tineye.com/<company>/rest/update/ \
-F "images[0]=@1.jpg" \
-F "images[1]=@2.jpg" \
-F "images[2]=@3.jpg"
URLs¶
curl -X PUT https://multicolorengine.tineye.com/<company>/rest/update/ \
-F "url=http://example.com/1.jpg" \
-F "image_id=9658451257" \
-F "filepath=path/folder/1.jpg" \
-F "ignore_background=true" \
-F "ignore_interior_background=false"
or
curl -X PUT https://multicolorengine.tineye.com/<company>/rest/update/ \
-F "urls[0]=http://example.com/1.jpg" \
-F "image_ids[0]=dd8d-6dc8-bf3f" \
-F "filepaths[0]=image_1.jpg" \
-F "urls[1]=http://example.com/2.jpg" \
-F "image_ids[1]=db9561-7cecb6" \
-F "filepaths[1]=image_2.jpg"
Response examples¶
JSON¶
{
"method": "update",
"status": "ok",
"error": [],
"result": [],
"stats": {
"time_download": 68.37,
"time_resize": 92.71,
"time_update": 124.35,
"time_total": 288.76
}
}
XML¶
<?xml version="1.0" encoding="utf-8"?>
<data>
<method>update</method>
<status>ok</status>
<error/>
<result/>
<stats>
<time_download>68.37</time_download>
<time_resize>92.71</time_resize>
<time_update>124.35</time_update>
<time_total>288.76</time_total>
</stats>
</data>