productAI

Start With API

It is recommended to use the ProductAI SDK if you are using one of its supported programming languages (currently: PHP, Python, Java and C#). If your preferred language is not yet supported, it is recommended to directly access ProductAI via its language agnostic RESTful API. When you use the API, please provide your account’s access_key_id into the HTTP header of your request. If you do not have this information handy, please log in to the web Console to obtain it (for the detailed instructions, read how to get your access_key_id).

A valid ProductAI API request’s header should contain:

NameTypeRequiredDescription
x-ca-versionStringYesAPI version, please fill ‘1’
x-ca-accesskeyidStringYesThe key assigned to user for API call, please read how to get your access_key_id

Create First Search Service

First, we’ll create a new image set. Please note that the API endpoint for image set operations is https://api.productai.com/image_sets/_0000014. For your information, these endpoint URLs are not intended to be reader friendly. Therefore, if friendly interfaces are required, it is recommended to use the SDK to access the service. Additionally, since the source code is available for each SDK, you may consider using them as best practice references for accessing the API.

One of the important concepts of ProductAI is the image set; conceptually, it is like a data table. The image set contains an image, which is conceptually like a record in the data table.

cURL

curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"name": "My Fashion Images", "description": "A set of fashion images for testing."}' \
https://api.productai.com/image_sets/_0000014

The response is in JSON format. The id is a unique identifier representing the new image set which you can reference in other APIs.

{
"created_at": "2017-12-13T08:40:51Z",
"creator_id": ...,
"description": "A set of fashion images for testing.",
"id": "l5qwws5f",
"modified_at": "2017-12-13T08:40:51Z",
"n_downloaded": 0,
"n_failed": 0,
"n_items": 0,
"name": "My Fashion Images",
"request_id": "53361e08-dfe1-11e7-a97c-664c03c7cfbb",
"status": "not-downloaded"
}

In the following sample, we add an image, which is the indexed object used in search. Add as many images to the image set as you’d like to fulfill your custom image search engine requirements.
add images into image set.

cURL

curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-d 'image_url=http://url/of/your/image.jpg' \
https://api.productai.com/image_sets/_0000014/l5qwws5f

Create a new image search service on the image set, tuned to a scenario, such as fashion. To know how to set the scenario parameter, see the ‘supported scenarios’ section of the search reference documentation.

cURL

curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"name": "My Fashion Search Engine", "scenario": "fashion_5_6"}' \
https://api.productai.com/image_sets/_0000014/l5qwws5f/services

The response is in JSON format. The returned id is a unique identifier representing your custom search engine service. You may reference this id in other APIs. Note that upon creation of the service, you can obtain status information such as the indexed_ratio, which is the percentage of images in your image set that have been indexed. Immediately upon creation of the service, it is expected that your index is of zero size. Grab a coffee and call the status API to see the progress of the indexing. Once it’s finished, you can proceed to querying the search engine.

{
"created_at": "2017-12-17T13:49:56Z",
"creator_id": ...,
"id": "790jvquc",
"image_set_id": "0mspcj1m",
"indexed_ratio": 0,
"last_indexed_time": null,
"last_updated_at": null,
"n_indexed": 0,
"name": " My Fashion Search Engine",
"request_id": "298f4aea-e331-11e7-a97c-664c03c7cfbb",
"scenario": "fashion_v3",
"status": "running",
"status_duration": 0
}

Send a query to your custom image search service.

cURL

curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-d 'url=http://url/of/your/query.jpg' \
https://api.productai.com/search/SERVICE_ID

The response is in JSON format. See the search reference documentation to learn the meaning of these fields. The following is provided for your reference to get a sample of the kind of response you might obtain when calling this API.

{
"detect_time": "0.000",
"detection_score": null,
"download_time": "0.004",
"ds": "70awubt0",
"is_err": 0,
"loc": [
0,
0,
1080,
1920
],
"preprocess_time": "0.005",
"request_id": "d2605570-e33a-11e7-9a73-92019f9dce87",
"results": [
{
"metadata": "10544127897",
"score": 0.6035475711762495,
"url": "http://url/of/your/first/result.jpg"
},
{
"metadata": "10544127898",
"score": 0.5894687892431159,
"url": "http://url/of/your/second/result.jpg"
},
...
],
"searchtime": "0.307",
"time": "0.324",
"ver": "20171113-135702"
}