What is an API?
The Everypixel API offers image recognition as a service. The API is built around a simple idea: you submit input data (an image) to a service and it returns predictions.
Image keywording API guide
Authorization and getting your API key
Before you start working with the Everypixel API, you need to register an account. After, you get your Client ID and Secret by logging into your Everypixel API account and going to Profile.
Your Client ID and Secret authenticate your API requests so that other people cannot use them. Remember that your Client ID and Secret must always be kept secret.
You can also use OAuth 2.0 authentication to improve security.
Payment
After registering your account, you will have 100 requests per day to fully test our algorithm.
If you want to receive more requests, you need to top up your personal account balance. The cost depends on the method you choose. For example, 1,000 requests for image keywording cost $0.6. Learn more about tariff plans for the Everypixel API here…
If your balance is low, we will send a warning email. You can determine the minimum balance limit in your profile on the Balance page to let us know when to send you a warning.
After exceeding the number of available requests from your tariff plan, you will see error 429.
Versions
The API version is part of URI. To use the v1 API, the request URI must start with /v1 followed by the API method.
https://api.everypixel.com/v1
Limits
API
You can submit simultaneously no more than 30 requests per second.
Image Keywording
The maximum number of words that the algorithm can produce is 50.
Video Keywording
The maximum number of words that the algorithm can produce is 50. The method successfully works only with video files lasting from 5 to 60 seconds. Increasing the length of the video reduces the relevance of the keywords.
Errors
Most of the errors returned by the API contain text in json format.
In addition, you may receive HTTP status codes with the following errors:
401 – if you don't have access to the specified endpoint. This can occur if your access token has expired.
429 – if you have exceeded the number of available requests from your tariff plan.
502 – if you have reached the maximum number of concurrent requests.
Keyword generation
To generate keywords, you need to submit a generation request.
1. You can choose the GET method and submit a request using curl, python or php.
2. You can choose the POST method and submit a request using a form.
Variable request parameters:
num_keywords – you can determine the maximum number of words to return. The maximum number of words that the algorithm can produce is 50. At the same time, the algorithm independently determines the exact number of keywords to be returned.
threshold – you can determine a minimum keyword relevance value (score), below which the algorithm will not return keywords
If you determine both parameters at the same time, for example, threshold=0.5&num_keywords=10, then the algorithm will produce either 10 keywords, or, if the determined score 0.5 occurs earlier, it will produce 7 keywords with a score higher than 0.5.
Getting results
keyword – the keyword that the algorithm has determined for your image.
score – the degree of relevance of the keyword to your image. The higher the score, the more precisely the keyword is defined and the higher it is on the list.
Image Requirements
When processing an image, the algorithm compresses it to 300x300px. This resolution allows to keep recognition accuracy and API speed high. If you upload images in a higher resolution, this will not affect the number or relevance of keywords, but it will slow down the API speed.
The algorithm is trained on images with real objects or those that have the outlines of real ones. Therefore, it can poorly recognize objects that do not exist in our world. For example, fantasy-style images: the algorithm may not recognize some magical creatures like a unicorn or dragon, and will most likely describe the image only with general keywords such as "illustration", "fantastic plot", etc. But the algorithm successfully recognizes illustrations if the details on them have the outlines of real objects.
URL image coding with the GET method
If you use the GET method to submit an image, you have to encode its URL before. We recommend using the Urlencode function to separate the image URL from the request.
It is required when the image URL contains special characters like '&' or '?'. For example, your image has the following address:
https://images.unsplash.com/photo-1564219563357-e29c471253b6?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=MnwxMTI4NzN8MHwxfGFsbHwyMjI3Nzh8fHx8fH
wyfHwxNjgzMTg1MDY3&ixlib=rb-4.0.3&q=80&w=400.
This URL contains special characters '&' or '?'. And if you pass it as a parameter to
https://api.everypixel.com/v1/keywords?url=<url>, you′ll get an error.
The algorithm can process the image, if the URL is in URL encoded form:
https%3A%2F%http://2fimages.unsplash.com/%2Fphoto-1564219563357-e29c471253b6%3Fcrop%3Dentropy%26cs%3Dtinysrgb%26fit%3Dmax%26fm%3Djpg%26ixid%3DMnwxMTI4N
zN8MHwxfGFsbHwyMjI3Nzh8fHx8fHwyfHwxNjgzMTg1MDY3%26ixlib%3Drb-4.0.3%26q%3D80%26w%3D400
When the POST method is used, URL encoding is not required.
Keywording Operation Speed
Maximum API speed is 30 RPS. This means that you can simultaneously submit no more than 30 requests per second. If you exceed this limit, you will see error 502.
The size of the transferred images affects the API speed. Therefore, we recommend pre-compressing images to 300px on the short side.
Data Security
We do not save your images when you submit an API request. Your images belong to you. They are downloaded through the aiohttp library. So, keywording is confidential, secure and constantly improving.