Skip to content

Generic Photo Tagging

PRICING DEMO

This page describes API for generic photo tagging service for stock photos. The API follows the general rules of Ximilar API as described in Section First steps.

This service API has only one endpoint running at this URL:

https://api.ximilar.com/photo/tags/v2/tags

See it in action ...

  • We are transparent company with public pricing and demo.
  • You can test your images on our test collection on Ximilar Demo for free!
  • Our python client library is available on gitlab and pypi

Active the service in Ximilar App

In order to get access to the Generic Photo Tagging service, please register at https://app.ximilar.com and then click on this Service on the main panel to make it accessible for your Ximilar account.

Tagging endpoint: /v2/tags

Given a list of image records, this method returns tags as predicted by the Generic Tagging services, together with probabilities (the level of certainty) for each of these tags.

Parameters:

  • records: list of photos to predict the tags for
    • must contain either of _url or _base64 field - see section image data for details
  • lang: language of the tags, currently: "cs", "en". Default: "en"
  • tagging_mode: settings of the tagging process and of returned data
    • complex - standard tagging mode, relevance values (probabilities) are returned (default)
    • simple - simple mode, some tags might be omitted, no probabilities returned
$ curl https://api.ximilar.com/photo/tags/v2/tags -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "lang": "en",
    "tagging_mode": "complex",
    "records": [
        { "_url": "https://bit.ly/2IymQJv" },
        {"_base64": "/9j/4AAQSkZJR...", "_id": "image_id"}
    ]
}'

from ximilar.client import GenericTaggingClient

generic_client = GenericTaggingClient(token="__API_TOKEN__")

result = generic_client.tags([{"_url": "__URL_PATH_TO_IMAGE__"}])
print(result['records'][0]['_tags'])

Returns:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - a JSON map with a status of the method processing. It contains these subfields:
      • code - a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
      • text - a text describing the status code
      • error_description - in case of the processing ended with error (codes 4XX), this field contains a detailed description of the error; this might include Java stack traces.
    • Example of statuses that can be returned:
      "status": {"code": 200, "text": "OK"}
      "status": {"code": 402, "text": "aborted by error", error_description="..."}
      "status": {"code": 500, "text": "unknown error", "error_description": "..."}
    • statistics - a map of various statistics about the processing. The only statistic included every time is
      • processing time - time of actual processing of the query [in seconds]
    • records - JSON array with the input records, each record enriched by field "_tags" with tagging mode "complex" the tags is an array with probabilities and tag names: "_tags": [ { "prob": 0.891, "name": "indoor"}, { "prob": 0.837, "name": "room"} ]
      with tagging mode "simple" the tags is an array with tag names:
      "_tags": ["room", "furniture", "family"]
CLICK TO SHOW JSON RESULT 

{
    "lang": "en" ,
    "tagging_mode": "complex",
    "status": {"text": "OK", "code": 200},
    "records": [
        {
            "_url": "http://example.com/myimage321.png",
            "_tags": [
                {
                    "prob": 0.8912695050239563,
                    "name": "indoor"
                },
                {
                    "prob": 0.8378337025642395,
                    "name": "room"
                }
            ],
            "_height": 500,
            "_width": 500
        },
       {
            "_id": "image_id",
            "_tags": [
                {
                    "prob": 0.82695050239563,
                    "name": "kitchen"
                },
                {
                    "prob": 0.7337025642395,
                    "name": "child"
                }
            ],
            "_height": 800,
            "_width": 600
       } 
    ],
    "statistics": {"processing time": 0.2893240451812744}
}

Base64 data are not in result

Please, note that the "_base64" data is not returned. Use "_id" or any other field to identify your image.

Service status check: /v2/ping

Description: returns a basic information about the service
No parameters
Example: 

$ curl https://api.ximilar.com/tagging/generic/v2/ping

Returns:
field info - a detailed text information about the similarity index

CLICK TO SHOW JSON RESULT 

{
   "info" : "Ximilar auto-tagging service...",
   "statistics" : {
      "processing time" : 0.002
   },
   "status" : {
      "text" : "OK",
      "code" : 200
   }
}