Broadly, the workflow for using the Visii platform is as follows:
- Setup account and receive your authentication token
- Create a new dataset
- Add content based on the Content Guide to the dataset (at least 200 items)
- Check the processing status for the content of your dataset
- Begin querying your content
- Update content
- Use the Analytics API to inform us of user behavior to get more user personalized results
- Check the Client Dashboard for insights into your account
# Creating a dataset and adding content
The first step to working with the platform is to create a new dataset. This is done via the datasets resource. The URL for the dataset is returned as part of the response when it is created.
Once a dataset exists, you can then begin adding content to it via it's datasets content resource. Newly added content must first be processed by the platform before it can be queried. The processing involves fetching each image and then analyzing it in order to build the dataset. During this process, it must be possible for the platform to fetch the image from the URL specified via an HTTP/S GET request. Once the processing is complete, the retrieved image is discarded and that item is then available via the Vision API.
There must be at least 200 items in the dataset before it is available.
As more content is added, the dataset is updated and the results improve. For example, new content may cause existing content to have updated similar items as more relevant content is added. The discovery feature will also improve as the user has more content to explore.
All of this is transparent to consumers of the Vision API, however it is worth taking it into account when considering your usage of the APIs. For example, it is reasonable to cache the results of the similar items feature of the Vision API to improve performance. However, you should consider that this data will become stale as the dataset is updated and so an appropriate expiration for the cache would be a good idea.
At present, a dataset must have a minimum of 200 pieces of content. Browsing the content will not begin until this minimum has been reached.
While new content processing is under way, you can check the status via the dataset resource. From there you will find how much content is still pending as well as if any errors have occurred.
# Processing failures
It is possible for errors to occur when processing new content. This may be because it was not possible to retrieve the image for the content or some error related to its processing has occurred. You can find the details of any errors that have occurred for a dataset at the dataset errors resource.
If an error has occurred because an image was not available or it's contents are corrupted, then you can simply fix the image and resubmit the content to the dataset content resource. The platform will recognize that the content has been submitted previously and will retry the processing.
Any failures caused by an internal Visii platform error will also be included in the list of errors for your information. If this occurs, Visii strives to resolve the issue as soon as possible and retry the processing automatically without requiring any intervention on your part.
Finally, any errors which occur for newly added content will not prevent other content from being processed. Therefore any other content submitted alongside the failed pieces that have been successfully processed will still be available from the Vision API.
# Querying datasets
A dataset can be queried using the Vision API once the number of pieces of content which have successfully completed processing reaches the minimum threshold. For details of the individual resources available from the Vision API, please see the relevant sections from the menu under Vision API.
In order to make any request to the Vision API, you must use the appropriate authentication token as described in the authentication section. The token for a given dataset can be found as part of the datasets resource.
# Adding new content
Once a dataset has processed its initial content and the total count of content contained within it has reached the minimum threshold, it is then available from the Vision API.
You can then add additional content using the dataset content resource as before. Processing and error handling then proceeds as described above.