A simple API for predicting ImageNet-1K labels of an image.
Project description
Image Tagger
A REST API for predicting ImageNet labels of images.
Description
Image Tagger is REST API for tagging images with ImageNet-1K labels. It wraps around an EfficientNetB3 model trained on ILSVRC dataset, exposing its functionality through a simple endpoint. The API was built using FastAPI python framework. It utilizes Tensorflow for executing deep learning models.
Quick Start
Image Tagger is available at PyPI and can be installed as following:
pip install image_tagger
In order to start the server use:
uvicorn image_tagger.main:app --host 0.0.0.0 --port 8000
Now the server should be up and running. If port 8000
is occupied
by something else on your machine, then try a different port.
Get the url of an image you like and perform a GET request to the API like:
GET localhost:8000/predictions?url=https://example.com/path/to/image.png
You will see a nice JSON response containing the label for your image. You can perform a GET request either by navigating to the above location with your browser, or by using a requests tool like Postman.
- Use your favorite browser and navigate to
localhost:8000/docs
.
You will see a nice documentation page for all the endpoints exposed by this API, along with the ability for interactively calling them.
- Navigate to
localhost:8000/redoc
.
You will see another version of the documentation. This one is for people who prefer the style of Redoc docs, instead of the Swagger UI based ones.
Endpoints
Currently, two endpoints are exposed by the API. The one for performing predictions and the other for obtaining versioning info about the live API.
GET /predictions
Predicts the ImageNet-1K labels of an image.
Returned labels can be filtered according to two parameters, top
and minconf
.
The first parameter controls the number of top-confidence labels to be
returned, sorted in descending order according to computed confidence. The
second one, limits the returned labels to the ones whose confidence score is
at least minconf
. These two parameters can be combined, applying the restrictions
of both, thus returning the most restrictive labels set.
By default, if top
and minconf
are omitted, only the label with the highest
confidence score is returned (the same as setting top=1
).
The image format can be any format supported be the Pillow library. For more info see: https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html
Image retrieval is performed through a GET request on given url.
Parameters
- url: The url of the image file. It can be any https or http url pointing to an image file. For example: 'https://example.com/path/to/image.jpg'
- top [optional]: The number of top ImageNet labels to be returned. The number of returned labels cannot exceed the number of available classes (top<=1000).
- minconf [optional]: The minimum confidence score a label should have in order to be
returned. It should be in the range
[0, 1]
.
Responses
Successful calls return a JSON containing the following attributes:
- url: The same url passed into the request.
- predictions: An array containing the predicted label objects in descending order.
Each object contains the following attributes:
- label: The predicted ImageNet-1K label.
- confidence: The confidence score of the label.
Example
{
"url": "https://example.com/path/to/image.jpg",
"predictions": [
{"label": "dog", "confidence": 0.78},
{"label": "wolf", "confidence": 0.06},
{"label": "tiger", "confidence": 0.03},]
}
Error 400: InvalidImage
In case the url
points to a resource that is not a supported image format,
response code is set to 400
and the following JSON is returned:
{"error": {
"type": "InvalidImage",
"detail": "Url is not pointing to a valid image format."
}}
Error 404: UnreachableURL
If the GET request on url
fails, then response code is set to 404
and the
following JSON is returned:
{"error": {
"type": "UnreachableURL",
"detail": "Url cannot be reached."
}}
Error 422: ValidationError
When the parameters of the request are invalid, response code is set to 422
and
a JSON describing the cause of the error is returned. An example response is
presented below:
{"error": {
"type": "ValidationError",
"detail": [{"loc": ["query", "url"],
"message": "URL scheme not permitted",
"type": "value_error.url.scheme"}]
}}
The only part of the response that is changing for different validation errors
is the content of detail
attribute. It is an array containing all validation
errors detected. The detail object of each detected violation contains the
following attributes:
- loc: An array describing the location of the error. For example
["query", "url"]
means that the value of query parameterurl
is invalid. - message: An informal message describing the cause of the error.
- type: A formal identifier of the error.
GET /
Returns general info about image tagger API.
This endpoint serves both as a placeholder for root path and as a way in order to retrieve versioning info.
Responses
Calls return a JSON containing the following attributes:
- description: A short textual description of the API.
- version: The version of the API in the format of semantic versioning (e.g. 1.0.0). For more info see: https://semver.org/
- revision: An integer indicating the current revision of the API. Each newer version of the API is guaranteed to have a greater revision number.
- author: API author's name.
- github_url: Link to the github repository containing the code of this API.
Documentation
Except from the REST endpoints described above, Image Tagger also provides a live version of their documentation.
/docs
: Swagger UI based documentation.
/redoc
: Redoc based documentation.
License:
This project is licensed under Apache License 2.0. A copy of this license is contained in current
project under LICENSE
file. It applies to all files in this project whether or not it is stated in them.
Copyright 2022 | Dimitrios S. Karageorgiou
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for image_tagger-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 43877e096a17ed5c5e7d167e6f814f42d5a9718fc702b5ad5ac5c4f818482235 |
|
MD5 | 4c3ad256c9112f20316ccb8d200cf931 |
|
BLAKE2b-256 | 3c77e28ab36189856bb24a309054e065d8324731b2787968c289ae77972eff81 |