Videntifier API Reference¶
Videntifier provides a RESTful HTTP API for inserting, querying and managing your image and video content.
Authentication¶
Videntifier API requires SSL. You must have a valid API token to make API requests. To authenticate a request, you should include the API token in the Authorization header.
All example requests in this documentation set the following HTTP header:
`Authorization: tw3v2Ep1K94ohFZPHQPX`
On signup, you will be provided with an API token.
Requests¶
The Videntifier API is a RESTful JSON API. Successful requests set the Content-Type header to application/json
, but in case of an error (such as a bad request), you may get a text/plain
response header.
If you submit a POST
or PUT
request you must set the Content-Type to multipart/form-data
.
Database hostname¶
Most endpoints in this documentation show examples of how to call the API using curl. As the actual hostname can change between clients, we refer to host
as the hostname of the database.
https://host.videntifier.com/api/v1/
On signup, you will be provided with the hostname.
Response Format¶
The Videntifier API uses HTTP status codes to indicate success or failure. A 2xx status code indicates success. A 4xx status code indicates an error with the request. A 5xx status indicates a failure on the server side.
Code | Status |
---|---|
200 | Success |
303 | Resource created elsewhere |
400 | Bad request |
401 | Authorization error |
404 | Not found |
409 | Conflict |
500 | Internal server error |
In case of a 400/5xx error, you will get an application/json
response that describes the error.
Example:
{ "error": { "code": "400", "message": "Invalid query parameter" } }
Pagination¶
Most list endpoints support pagination. You can change the number of records returned and which page to return by specifying the following parameters:
page
: Which page to return.page_size
: How many records to list per page. By default, 50 records are returned. The maximum allowed value for this field is 100.
Pagination information is included in a _metadata
value in the JSON response:
"_metadata": { "page": "1", "page_size": "50", "nr_pages": "20", "nr_results": "995", "links": { "self": "https://host.videntifier.com/api/v1/contents&page=1", "next": "https://host.videntifier.com/api/v1/contents&page=2", "prev": null, "first": "https://host.videntifier.com/api/v1/contents", "last": "https://host.videntifier.com/api/v1/contents&page=995" } }
API Endpoints Overview¶
URL | HTTP Method | Description |
---|---|---|
/account | GET | Get account info |
/profiles | GET | List profiles |
/query | POST | Query an image or video |
/query_async | POST | Query an image or video asynchronously |
/query_results | GET | Retrieve a persisted query result |
/query_sw | POST | Query a video in a "source within" mode |
/query_sw_async | POST | Query a video in a "source within" mode asynchronously |
/query_results_sw | GET | Retrieve a persisted "source within" query result |
/insert | POST | Insert an image or video |
/insert_async | POST | Insert an image or video asynchronously |
/jobs | GET | List jobs |
/jobs/:id | GET | Get job status |
/jobs/:id | DELETE | Delete a job status |
/contents | GET | List inserted images and videos |
/contents/:id | GET | Get info about an image or video |
/contents/:id | DELETE | Delete an image or video |
/contents/:id/metadata | PUT | Update metadata |
/users | GET | List users |
/users | POST | Create user |
/users/:id | PATCH | Update user information |
/users/:id | DELETE | Delete user |
/users/:id | GET | Get info about user |
/dbinfo | GET | Get info about database |
Get account info¶
Endpoint
GET /account
Required Parameters
None
Optional Parameters
None
Response
The response shows details about your account, including how much content you have inserted into the database. The following fields are always present in the response:
organization
: The name of your organization.nr_points
: How many visual points all users from your organization have inserted into the database.max_points
: The maximum number of visual points all users from your organization can insert. If this limit is reached, you might get an error when inserting new content. If set to 0, there is no limit.nr_images
: How many images all users from your organization have inserted into the database.nr_videos
: How many videos all users from your organization have inserted into the database.nr_video_seconds
: How many seconds of video content all users from your organization have inserted into the database.users
: Shows the username of each user in the organization along with how much content each user has inserted into the database.
Example request:
curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/account'
Example response:
{ "data": { "account": { "organization": "videntifier", "nr_points": "34627", "nr_images": "54", "nr_videos": "2", "nr_video_seconds": "262", "max_points": "100000", "users": [ { "username": "user1", "nr_images": "54", "nr_videos": "2", "nr_video_seconds": "262", "nr_points": "34627" } ] } } }
List profiles¶
Endpoint
GET /profiles
Required Parameters
None
Optional Parameters
None
Response
The response lists all available profiles. A profile can be chosen per request when querying or inserting into the database. Currently, profiles only affect the signature extraction, but in later versions, profiles might be extended to affect other parameters.
Depending on the use case, we want to be able to tune the extraction settings based on whether we are querying or inserting an image or video. To support this, each profile defines the following parameters:
image_query
: The extraction settings when querying an image.image_insert
: The extraction settings when inserting an image.video_query
: The extraction settings when querying a video.video_insert
: The extraction settings when inserting a video.
Example request:
curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/profiles'
Example response:
{ "data": { "profiles": [ { "name": "hq", "description": "High quality extraction mode", "extraction": { "image_query": "", "image_insert": "--high-quality", "video_query": "", "video_insert": "--high-quality" } }, { "name": "hq-sw", "description": "Optimized extraction mode for source-within", "extraction": { "image_query": "", "image_insert": "--high-quality", "video_query": "", "video_insert": "--high-quality --scene-mode=REALTIME --scene-max-duration=10" } } ] } }
Query an image or video¶
Endpoint
POST /query
Required Parameters
The /query endpoint supports multiple ways to query a content. If the content is already in the database, you can query it by its content_id
. You can also provide a download_url
that instructs the database to first download the content and then query it. You can also upload the content or its signature directly by writing it to the form file
.
To query, you must provide one of the parameters:
content_id
(form-field): The contentID of the image or video you want to query.download_url
(form-field): A valid URL where the image or video you want to query can be downloaded from.file
(form-field): A local file on your machine that you will upload to the database for querying (file can be an image, video or .desc72 signature).
Note
If more than one parameter is specified, you will receive an HTTP Bad Request error.
Optional Parameters
profile
: The profile you want to use for the query. Note that if the signature was already computed (e. query by content_id or uploaded as desc72), the profile is ignored.include_locations
: If set to true, the query response will include an array of locations showing detailed match information about all matching content.include_query_stats
: If set to true, the query response will include statistics about the query, including how much time each part of the query took.include_points
: If set to true, each match location will include an array of visual point coordinates in string format "x_query,y_query,x_match,y_match". The match will also include bounding boxes that encompass all matching descriptors in both the query and match scenes. This option is only available if the query includes locations. Currently this feature is only supported for images.
Response
At the root of the JSON query response, the following fields are present:
query
: JSON object with information about performed query. It has the following fields:id
: Query response is persisted and can be retrieved at a later time using query result id. Persisted result expires after some time, for details see Retrieve a persisted query resulttype
: Type of the content queried. Can be 'video' or 'image'.download_url
: This field is present in the response if the query was performed using URL. It contains the queried URL.content
: This object contains information about the queried object (for field description see Get info about an image or video)content_id
: This field is present in the response if the query was performed using content id and it contains content id that was used in the query.file
: This field is present in the response if the query was performed using file upload. It contains the filename of the file used.
visualization_url
: URL to the visual user interface where query results can be examined in a browser._metadata
: Pagination information.query_stats
: Query statistics.matches
: An array of matches, where each match has the following fields:content
: The content that is matching. For field description see Get info about an image or videocoverage
: A percentage of the query video matching to the match ornull
if the query media type is an image.match_type
: Whether the match is a similarity match or a visual copy.nr_matching_points
: How many points in the query are matching this match.locations
: If theinclude_locations
query param is set to true, then each match will also include a list of matching locations between the query and match. This is only relevant for videos. Each location has the following fields:query_locations
: An array of query locations matching at this location. If the query is an image this will always be an empty array.match_locations
: An array of match locations matching at this location. If the match is an image this will always be an empty array.query_perc
: A percentage of the area in the query that is matching at this location(between 0-100%).match_perc
: A percentage of the area in the match that is matching at this location (between 0-100%).scene_id
: The scene_id of the match that was matching at this location.visual_copy
: Set to true if bothquery_perc
andmatch_perc
are above 85, indicating that the result is an exact match. Note that an image can be considered a visual copy even though it has been modified to some extent (mirrored or rotated, for example).
related_matches
: For accounts where this functionality is enabled, the query will perform a more extensive search. In addition to direct matches, the query result will also contain an array of related matches. Related matches are indirectly related to queried content. For details, see [Related matches][#related-matches]
Example request:
To query a file by providing download_url:
curl -X POST \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ -F 'download_url=URL' \ 'https://host.videntifier.com/api/v1/query'
curl -X POST \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ -F 'file=@/path/to/file' \ 'https://host.videntifier.com/api/v1/query?include_locations=true&include_points=true'
Example response
{ "data": { "query": { "content": { "content_id": "996", "created_at": "2018-01-10T05:51:03.658786Z", "duration": null, "file_size": "799450", "filename": "image.jpeg", "insert_method": "content", "metadata": {}, "nr_points": "303", "scaled_height": "360", "scaled_width": "240", "sha1sum": "1f914ad2c9d7bbcbd399ff450ad21e290951d537", "type": "image", "url": "https://localhost:9000/data/1f914ad2c9d7bbcbd399ff450ad21e290951d537.png", "username": "user1" }, "content_id": "996", "id": "1", "type": "image" }, "matches": [ { "content": { "content_id": "997", "created_at": "2017-10-11T09:22:44.566794Z", "duration": null, "file_size": "100495", "filename": "image.jpg", "insert_method": "content", "metadata": {}, "nr_points": "531", "scaled_height": "360", "scaled_width": "240", "sha1sum": "3bbbb3248dc4e727545ef1835462ae9954b141ad", "type": "image", "url": "https://host.videntifier.com/data/3bbbb3248dc4e727545ef1835462ae9954b141ad.jpg", "username": "user1" }, "coverage": null, "locations": [ { "match_locations": [], "match_perc": "100.00", "query_locations": [], "query_perc": "100.00", "scene_id": "997", "visual_copy": true, "bounding_boxes": { "match": { "max_x": "367", "min_x": "0", "max_y": "197", "min_y": "0" }, "query": { "max_x": "367", "min_x": "0", "max_y": "197", "min_y": "0" } }, "points": [ "289,68,289,68", "336,54,336,54", "136,42,136,42", ] } ], "match_type": "visual_copy", "nr_matching_points": "443" } ], "query_stats": { "nr_frames_queried": "3", "nr_points_queried": "1463", "time_fetch_points": "14ms", "time_init_matching": "2ms", "time_matching": "9ms", "time_query": "26ms", "time_total_ms": "107ms" }, "related_matches": [ { "content": { "content_id": "1011", "created_at": "2018-02-12T18:07:10.513584Z", "duration": null, "file_size": "425377", "filename": "image2.png", "insert_method": "content", "metadata": {}, "nr_points": "1005", "scaled_height": "512", "scaled_width": "512", "sha1sum": "28bd1cdf0df08477c65b1749ef2f8426d16c149c", "type": "image", "url": "https://localhost:9000/data/28bd1cdf0df08477c65b1749ef2f8426d16c149c.png", "username": "user2" }, "locations": [ { "match_locations": [], "match_perc": "100.00", "query_locations": [], "query_perc": "100.00", "scene_id": "1011", "visual_copy": true, "bounding_boxes": { "match": { "max_x": "367", "min_x": "0", "max_y": "197", "min_y": "0" }, "query": { "max_x": "367", "min_x": "0", "max_y": "197", "min_y": "0" } }, "points": [ "289,68,289,68", "336,54,336,54", "136,42,136,42", ] } ], "related_content_id": "997", "related_depth": "1" } ], "_metadata": { "links": { "first": "https://host.videntifier.com/api/v1/query_results/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&include_locations=true&page=1&page_size=50", "last": "https://host.videntifier.com/api/v1/query_results/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&include_locations=true&page=1&page_size=50", "next": null, "prev": null, "self": "https://host.videntifier.com/api/v1/query_results/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&include_locations=true&page=1&page_size=50" }, "nr_pages": "1", "nr_results": "1", "page": "1", "page_size": "50" }, "visualization_url": "https://ui.videntifier.com/api/v1/query_results/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD" } }
Retrieve a persisted query result¶
Endpoint
GET /query_results/:id
Required Parameters
access_token
: Access token, provided as part ofquery_result_url
from the original query response.
Optional Parameters
page
: Which page to return.page_size
: How many records to list per page. By default 50 records are returned. The maximum allowed value for this field is 100.filter_attr
: Attribute used to filter the list of matches. Any of the attributes in match content information can be used as a filter field, as well ascoverage
,match_type
andnr_matching_points
. This attribute is not set by default.filter
: Value applied to filter attribute. This attribute is not set by default.sort_attr
: Attribute used to sort the list of matches. Any of the attributes in match content information can be used as a filter field, as well ascoverage
,match_type
andnr_matching_points
. The default value for this attribute isnr_matching_points
.dir
: Sort direction. Possible values areasc
to sort entries in ascending order ordesc
to sort them in descending order. The default value for this attribute isdesc
.include_locations
: If set to true, the query response will include an array of locations showing detailed match information about all matching content.include_query_stats
: If set to true, the query response will include statistics about the query, including how much time each part of the query took.
Response
Query result response will be the same as the original /query response (See Query an image or video)
Example request:
curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/query_results/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&include_locations=true'
Query asynchronously¶
Endpoint
POST /query_async
Required Parameters
Same as /query
Optional Parameters
Same as /query
Response
The async query response will respond with information about the job that was created from the request. The user can then call /jobs with the returned id for further information about the job.
Example request:
curl -X POST \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ -F 'file=@/path/to/file' \ 'https://host.videntifier.com/api/v1/query_async?include_locations=true'
Example response:
{ "data": { "job": { "id": "1" } } }
Query a video in a "source within" mode¶
Endpoint
POST /query_sw
Required Parameters
Same as /query
Optional Parameters
profile
: The profile you want to use for the query. Note that if the signature was already computed (e. query by content_id or uploaded as desc72), the profile is ignored.include_query_stats
: If set to true, the query response will include statistics about the query, including how much time each part of the query took.
Description
When querying a video in a "source within" mode, it queries the database (like default search). It then processes the matches it gets and only returns matches where the query video (the source) is contained within. To detect whether these matches result in a "source within" match, a few things are computed on the database side, including:
- For each matching video/stream, all query/match locations are grouped together and each group is checked independently for whether its a "source within" match.
- Each group is given a score based on how many fingerprints it shares with the query video.
- Each group maintains statistics such as average query percentage, number of unique query locations matching to it, group and query duration, etc.
- Groups with stats that do not exceed defined minimum values are skipped.
- For the remaining groups (and this is key), the group score (computed in step 2) is multiplied by the ratio of how much each of the individual stats exceed their minimum value.
- If the computed score is above a certain minimum value, the group is declared a "source within" match.
- Based on how much the score is above the minimum, a confidence value is returned. If it just passes the minimum, it gets a confidence value of "1:10". However if the score exceeds the minimum, an increasingly larger confidence value is returned: "1:100","1:1000","1:10000","1:100000" and finally "1:1000000".
This confidence value can be used to indicate weak/strong "source within" matches. For example, if the query video contains logos throughout the bottom that match another different video with a similar logo, then in rare cases this might result in a "source within" match, but then usually the query percentage is lower, causing a low confidence value, which can be filtered out or ignored.
Note
This mode works best when the query video is less than a few minutes long. 30-60 seconds is optimal but it should work rather well for any video shorter than 5 minutes.
Note
This mode is only for querying videos. If you try to query an image, you should get a bad request (code 400) HTTP error
Response
At the root of the JSON query response, the following fields are present:
query
: JSON object with information about performed query. It has the following fields:id
: Query response is persisted and can be retrieved at a later time using query result id. Persisted result expires after some time, for details see Retrieve a persisted "source within" query resulttype
: Type of the content queried. Can be only 'video' forsource_within
queries.download_url
: This field is present in the response if the query was performed using URL. It contains the queried URL.content
: This object contains information about the queried object (for field description see Get info about an image or video).content_id
: This field is present in the response if the query was performed using content id and it contains the content id that was used in the query.file
: This field is present in the response if the query was performed using file upload. It contains the filename of the file used.
visualization_url
: URL to the visual user interface where query results can be examined in a browser._metadata
: Pagination information.query_stats
: Query statistics.matches
: Query result response contains same array of matches as normal/query
response (See Query an image or video) with the only difference thatsource_within
response won't containlocations
, but will contain parametersconfidence
andsource_within
. For their description, see above (Description section).
Example request:
curl -X POST \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ -F 'file=@/path/to/file' \ 'https://host.videntifier.com/api/v1/query_sw'
Example response
{ "data": { "query": { "id": "1", "type": "image", "content_id": "996", "content": { "content_id": "996", "duration": null, "metadata": {}, "url": "https://localhost:9000/data/1f914ad2c9d7bbcbd399ff450ad21e290951d537.png", "sha1sum": "1f914ad2c9d7bbcbd399ff450ad21e290951d537", "type": "image", "filename": "image.jpeg", "file_size": "799450", "scaled_height": "360", "scaled_width": "240", "nr_points": "303", "created_at": "2018-01-10T05:51:03.658786Z", "username": "user1", "insert_method": "content" } }, "query_stats": { "nr_points_queried": "1463", "nr_frames_queried": "3", "time_fetch_points": "14ms", "time_init_matching": "2ms", "time_matching": "9ms", "time_query": "26ms", "time_total_ms": "107ms" }, "_metadata": { "page": "1", "page_size": "50", "nr_pages": "1", "nr_results": "1", "links": { "self": "https://host.videntifier.com/api/v1/query_results_sw/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&page=1&page_size=50", "next": null, "prev": null, "first": "https://host.videntifier.com/api/v1/query_results_sw/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&page=1&page_size=50", "last": "https://host.videntifier.com/api/v1/query_results_sw/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&page=1&page_size=50" } }, "visualization_url": "https://ui.videntifier.com/api/v1/query_results_sw/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD", "matches": [ { "content": { "content_id": "997", "duration": null, "metadata": {}, "url": "https://host.videntifier.com/data/3bbbb3248dc4e727545ef1835462ae9954b141ad.jpg", "sha1sum": "3bbbb3248dc4e727545ef1835462ae9954b141ad", "type": "image", "filename": "image.jpg", "file_size": "100495", "scaled_height": "360", "scaled_width": "240", "nr_points": "531", "created_at": "2017-10-11T09:22:44.566794Z", "username": "user1", "insert_method": "content" }, "confidence": "1:10000", "source_within": [ { "starts_at": "900.38" } ] } ] } }
Retrieve a persisted "source within" query result¶
Endpoint
GET /query_results_sw/:id
Required Parameters
access_token
: Access token, provided as part ofquery_result_url
from the original query response.
Optional Parameters
page
: Which page to return.page_size
: How many records to list per page. By default 50 records are returned. The maximum allowed value for this field is 100.filter_attr
: Attribute used to filter the list of matches. Any of the attributes in match content information can be used as a filter field, as well as aconfidence
field. This attribute is not set by default.filter
: Value applied to filter attribute. This attribute is not set by default.sort_attr
: Attribute used to sort the list of matches. Any of the attributes in match content information can be used as a filter field, as well asconfidence
field. The default value for this attribute isconfidence
.dir
: Sort direction. Possible values areasc
to sort entries in ascending order ordesc
to sort them in descending order. The default value for this attribute isdesc
.include_query_stats
: If set to true, the query response will include statistics about the query, including how much time each part of the query took.
Response
The query result response will be same as the /query_sw query response(See Query a video in a "source within" mode)
Example request:
curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/query_results_sw/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&include_locations=true'
Query "source within" asynchronously¶
Endpoint
POST /query_sw_async
Required Parameters
Same as /query_sw
Optional Parameters
Same as /query_sw
Response
The async query_sw response will respond with information about the job that was created from the request. The user can then call /jobs with the returned id for further information about the job.
Example request:
curl -X POST \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ -F 'file=@/path/to/file' \ 'https://host.videntifier.com/api/v1/query_sw_async'
Example response:
{ "data": { "job": { "id": "1" } } }
Insert an image or video¶
Endpoint
POST /insert
Required Parameters
The /insert endpoint supports two ways to insert content. You can upload the content or its signature directly by writing it to the form file
. You can also provide a download_url
that instructs the database to first download the content and then insert it.
download_url
(form-field): A valid URL where the image or video you want to insert can be downloaded from.file
(form-field): The file path of the image/video/desc72 you want to insert.
Note
If more than one parameter is specified, you will receive an HTTP Bad Request error.
Optional Parameters
profile
: The profile you want to use for the insert. Note that if the signature was already computed (uploaded as desc72), the profile is ignored.include_scenes
: If set to true, the insert response will include a scenes array listing all scenes attached to the content.metadata
(form-field): A valid JSON string with any custom metadata you want to save with the inserted content.
Response
The insert response will return the same information as the Get info about an image or video endpoint for the newly inserted content.
Example request:
curl -X POST \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ -F 'file=@/path/to/file' \ -F 'metadata={"internal_id": "927234"}' \ 'https://host.videntifier.com/api/v1/insert'
Example response:
{ "data": { "content": { "content_id": "1001", "duration": null, "metadata": { "internal_id": "927234" }, "url": "https://host.videntifier.com/data/3bbbb3248dc4e727545ef1835462ae9954b141ad.jpg", "sha1sum": "3bbbb3248dc4e727545ef1835462ae9954b141ad", "type": "image", "filename": "image.jpg", "file_size": "123456", "scaled_height": "360", "scaled_width": "240", "nr_points": "1234", "created_at": "2017-10-11T09:22:32Z", "username": "user1", "insert_method": "content" } } }
Insert asynchronously¶
Endpoint
POST /insert_async
Required Parameters
Same as /insert
Optional Parameters
Same as /insert
Response
The async insert response will respond with information about the job that was created from the request. The user can then call /jobs with the returned id for further information about the job.
Example request:
curl -X POST \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ -F 'file=@/path/to/file' \ -F 'metadata={"internal_id": "927234"}' \ 'https://host.videntifier.com/api/v1/insert_async'
Example response:
{ "data": { "job": { "id": "1" } } }
List jobs¶
Endpoint
GET /jobs
Required Parameters
None
Optional Parameters
page
: Which page to return.page_size
: How many records to list per page. By default, 50 records are returned. The maximum allowed value for this field is 100.filter_attr
: Attribute used to filter the list of jobs. Valid filter field attributes:username
,type
,status
. This attribute is not set by default.filter
: Value applied to filter attribute. This attribute is not set by default.sort_attr
: Attribute used to sort the list of jobs. Valid sort field attributes:username
,type
,status
,created_at
. The default value for this attribute iscreated_at
.dir
: Sort direction. Possible values areasc
to sort entries in ascending order ordesc
to sort them in descending order. The default value for this attribute isdesc
.
Response
The response lists jobs information in jobs
array. For details about the fields, see Get job status
curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/jobs?page=1&page_size=2'
{ "data": { "jobs": [ { "id": "3", "created_at": "2000-04-24T17:29:21.79949Z", "username": "user1", "status": "success", "method": "content", "progress": "0", "type": "insert", "result_url": "https://host.videntifier.com/api/v1/contents/9971", "error": null }, { "id": "2", "created_at": "2000-04-24T17:29:21.79949Z", "username": "user1", "status": "success", "method": "content_id", "progress": "0", "type": "query", "result_url": "https://host.videntifier.com/api/v1/query_results/2?access_token=bQuzaiUO398OKCEJAw3uFJkx6zfZrbgq", "error": null } ], "_metadata": { "page": "1", "page_size": "2", "nr_pages": "1", "nr_results": "2", "links": { "self": "https://host.videntifier.com/api/v1/jobs?page=1&page_size=2", "next": null, "prev": null, "first": "https://host.videntifier.com/api/v1/jobs?page=1&page_size=2", "last": "https://host.videntifier.com/api/v1/jobs?page=1&page_size=2" } } } }
Get job status¶
Endpoint
GET /jobs/:id
Required Parameters
None
Optional Parameters
None
Response
The response includes the following fields:
id
: The job IDusername
: The username of the user that requested the job.created_at
: The date when the job was requested.status
: The status of the job. If it is still processing, it can be any of:download
,extract
,query
,insert
. If the job is finished, the status can be:finished
,error
,cancelled
.progress
: (For videos) The progress of visual point extraction, measured on the scale of 0-100.type
: The type of the job, can be eitherquery
orinsert
.method
: The method used to provide the content for the job. If the content to process was uploaded directly to the API, the value will becontent
. If a remote URL was supplied, the value will beurl
. If a file with extracted visual points was used instead of the content itself, the value will bedesc72
. For query jobs only: If the content was queried using its ID within the database, the value of this field will becontent_id
.result_url
: If a job finished successfully, this field contains a link to the location of the created resource.error
: If a job finished with status error, this field will include two fields,code
andmessage
. Otherwise it will be null.
The response will tell you whether the job is finished or not. If not finished, it will return
status 200. For videos, the field progress
will indicate visual point extraction progress.
If the job is finished, the request will return a status 303 with a link to the newly
created resource in field Location
in the header.
Example request (-i to include header response):
curl -i -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/jobs/1'
Example response from finished job:
HTTP/1.1 303 See Other Access-Control-Allow-Headers: Accept, Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE Access-Control-Allow-Origin: * Content-Type: application/json Location: https://host.videntifier.com/api/v1/query_results_sw/2?access_token=xq87GN7JoX2AeXeyJWNtyR9Euz2CQQxq Date: Mon, 29 Jan 2018 15:40:27 GMT Content-Length: 0 { "data": { "job": { "id": "1", "created_at": "2000-04-24T17:29:21.79949Z", "username": "user1", "status": "success", "method": "content_id", "progress": "0", "type": "query", "result_url": "https://host.videntifier.com/api/v1/query_results_sw/2?access_token=xq87GN7JoX2AeXeyJWNtyR9Euz2CQQxq", "error": null } } }
Example response from processing job:
HTTP/1.1 200 OK Access-Control-Allow-Headers: Accept, Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE Access-Control-Allow-Origin: * Content-Type: application/json Date: Mon, 29 Jan 2018 15:42:12 GMT Content-Length: 33 { "data": { "job": { "id": "1", "created_at": "2000-04-24T17:29:21.79949Z", "username": "user1", "status": "extract", "method": "content_id", "progress": "38", "type": "query", "result_url": null, "error": null } } }
Example response from failed job:
HTTP/1.1 200 OK Access-Control-Allow-Headers: Accept, Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE Access-Control-Allow-Origin: * Content-Type: application/json Date: Mon, 29 Jan 2018 15:42:12 GMT Content-Length: 33 { "data": { "job": { "id": "1", "created_at": "2000-04-24T17:29:21.79949Z", "username": "user1", "status": "error", "method": "content_id", "progress": "0", "type": "query", "result_url": null, "error": { "code": "500", "message": "Internal Server Error" } } } }
Delete job¶
Endpoint
DELETE /jobs/:id
Required Parameters
None
Optional Parameters
None
Response
If the job is being actively processed at the time of the delete request, the request will return a 409 conflict status code.
Example request:
curl -X DELETE \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/jobs/2'
Example response:
{ "data:": { "message": "Resource has been deleted" } }
List inserted images and videos¶
Endpoint
GET /contents
Required Parameters
None
Optional Parameters
include_matches
: If set to true, each content will include an array of matching contents.include_scenes
: If set to true, each content will include an array of scenes attached to the content.include_points
: If set to true, each content will include an array of visual point coordinates. Currently this feature is only supported for images.page
: Which page to return.page_size
: How many records to list per page. By default 50 records are returned. The maximum allowed value for this field is 100.filter_attr
: Attribute used to filter the list of contents. Any of the attributes in content information can be used as a filter field. This attribute is not set by default.filter
: Value applied to filter attribute. This attribute is not set by default.sort_attr
: Attribute used to sort the list of contents. Any of the attributes in content information can be used as a sort field. The default value for this attribute iscreated_at
.dir
: Sort direction. Possible values areasc
to sort entries in ascending order ordesc
to sort them in descending order. The default value for this attribute isdesc
.
Response
The response lists inserted contents information in contents
array. For details about the fields, see Get info about an image or video
Example request:
curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/contents?include_scenes=true&include_matches=true'
Example response:
{ "data": { "_metadata": { "page": "1", "page_size": "50", "nr_pages": "1", "nr_results": "1", "links": { "self": "https://host.videntifier.com/api/v1/contents?page=1&page_size=50", "next": null, "prev": null, "first": "https://host.videntifier.com/api/v1/contents?page=1&page_size=50", "last": "https://host.videntifier.com/api/v1/contents?page=1&page_size=50" } }, "contents": [ { "content_id": "1000", "duration": null, "metadata": {}, "url": "https://host.videntifier.com/data/913238e963e854d4909ba920eed4e6cceb5c5360.jpg", "sha1sum": "913238e963e854d4909ba920eed4e6cceb5c5360", "type": "image", "filename": "3.jpg", "file_size": "100495", "scaled_height": "360", "scaled_width": "240", "nr_points": "543", "created_at": "2017-10-11T09:22:44.566794Z", "username": "user1", "insert_method": "content", "matches": [ { "content_id": "1002", "duration": null, "metadata": {}, "url": "https://host.videntifier.com/data/ba920eed4e6cceb5c5360913238e963e854d4909.jpg", "sha1sum": "ba920eed4e6cceb5c5360913238e963e854d4909", "type": "image", "filename": "9.jpg", "file_size": "4950", "scaled_height": "360", "scaled_width": "280", "nr_points": "845", "created_at": "2017-10-11T01:20:40.794566Z", "username": "user1", "insert_method": "content" } ], "scenes": [ { "locations": [], "scene_id": "1001" } ] } ] } }
Get info about an image or video¶
Endpoint
GET /contents/:id
Required Parameters
None
Optional Parameters
include_matches
: If set to true, the content will include an array of matching contents.include_scenes
: If set to true, the content will include an array of scenes attached to the content.include_points
: If set to true, the content will include an array of visual point coordinates. Currently this feature is only supported for images.
Response
The response includes following fields:
content_id
: The contentID of the inserted content.created_at
: The date when the content was inserted.duration
: The duration of the video in seconds ornull
if the content is an image.file_size
: The file size of the content.scaled_height
: The height used when calculating the visual points for the media.scaled_width
: The width used when calculating the visual points for the media.filename
: The filename of the content.insert_method
: How the content was inserted, possible values arecontent
,url
ordesc72
.nr_points
: The number of visual points extracted from the content that were inserted into the database.metadata
: Custom metadata attached to the content.sha1sum
: The sha1sum of the content.type
: The type of content (image or video).url
: A direct URL to the content. If theinsert_method
isdesc72
then URL isnull
as the content is not stored in the database.username
: The username of the user who inserted the content.scenes
: If theinclude_scenes
query param is set to true, this will contain JSON array with following fields:locations
: A list of locations which the scene describes.scene_id
: The sceneID of the inserted scene describing the image or video scene.
Example request:
curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/contents/1000?include_scenes=true&include_points=true&include_matches=true'
Example response:
{ "data": { "content": { "content_id": "1000", "duration": null, "metadata": {}, "url": "https://host.videntifier.com/data/913238e963e854d4909ba920eed4e6cceb5c5360.jpg", "sha1sum": "913238e963e854d4909ba920eed4e6cceb5c5360", "type": "image", "filename": "3.jpg", "file_size": "100495", "scaled_height": "360", "scaled_width": "240", "nr_points": "543", "created_at": "2017-10-11T09:22:44.566794Z", "username": "user1", "insert_method": "content", "matches": [ { "content_id": "1002", "duration": null, "metadata": {}, "url": "https://host.videntifier.com/data/ba920eed4e6cceb5c5360913238e963e854d4909.jpg", "sha1sum": "ba920eed4e6cceb5c5360913238e963e854d4909", "type": "image", "filename": "9.jpg", "file_size": "4950", "scaled_height": "360", "scaled_width": "280", "nr_points": "845", "created_at": "2017-10-11T01:20:40.794566Z", "username": "user1", "insert_method": "content" } ], "scenes": [ { "locations": [], "scene_id": "1001" } ], "points": [ { "x": "15", "y": "123" } ] } } }
Delete an image or video¶
Endpoint
DELETE /contents/:id
Required Parameters
None
Optional Parameters
None
Response
Example request:
curl -X DELETE \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/contents/999'
Example response:
{ "data:": { "message": "Resource has been deleted" } }
Update metadata¶
Endpoint
PUT /contents/:id/metadata
Required Parameters
metadata
(form-field): The new metadata you want to save.
Optional Parameters
None
Response
This endpoint updates the metadata attached to the specified content. The new metadata will replace the existing metadata (if any).
Example request:
curl -X PUT \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ -F 'metadata={"internal_id": "927234", "internal_name": "ab2281_11"}' \ 'https://host.videntifier.com/api/v1/contents/1000/metadata'
Example response:
{ "data:": { "message": "Metadata was updated successfully" } }
List users¶
Endpoint
GET /users
Required Parameters
None
Optional Parameters
page
: Which page to return.page_size
: How many records to list per page. By default, 50 records are returned. The maximum allowed value for this field is 100.filter_attr
: Attribute used to filter user list. Any of the attributes in user information can be used as a filter field. This attribute is not set by default.filter
: Value applied to filter attribute. This attribute is not set by default.sort_attr
: Attribute used to sort user list. Any of the attributes in user information can be used as a sort field. The default value isusername
.dir
: Sort direction. Possible values areasc
to sort entries in ascending order ordesc
to sort them in descending order. The default value isasc
.
Response
The response lists all registered users. Each user information has the following fields:
id
: The ID of the user.username
: The username of the user.email
: The email of the user.api_token
: API token of the user. API token is not displayed in cases when the user doesn't have necessary rights to view it.can_insert
: Signifies whether the user has right to insert content. Possible values aretrue
orfalse
.role
: User's role. Possible values areadmin
orbasic
. Rolebasic
allows basic API usage, while roleadmin
allows to modify/delete all content and users.visibility
: User's visibility setting. Possible values areprivate
,public
orglobal
. Contents inserted by the user withprivate
visibility setting can only be viewed/searched by this user. Contents inserted by the user withpublic
visibility setting can be viewed/searched by any other user within the same organization. Contents inserted by the user withglobal
visibility setting can also be viewed/searched by other organizations.
Example request:
curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/users?sort_attr=id&dir=desc&filter_attr=username&filter=vid'
Example response:
{ "data": { "users": [ { "id": "1", "username": "user1", "email": "videntifier@videntifier.com", "api_token": "tw3v2Ep1K94ohFZPHQPX", "can_insert": true, "role": "admin", "visibility": "global" } ], "_metadata": { "page": "1", "page_size": "50", "nr_pages": "1", "nr_results": "1", "links": { "self": "https://host.videntifier.com/api/v1/users?dir=desc&filter=vid&filter_attr=username&page=1&page_size=50&sort_attr=id", "next": null, "prev": null, "first": "https://host.videntifier.com/api/v1/users?dir=desc&filter=vid&filter_attr=username&page=1&page_size=50&sort_attr=id", "last": "https://host.videntifier.com/api/v1/users?dir=desc&filter=vid&filter_attr=username&page=1&page_size=50&sort_attr=id" } } } }
Create user¶
Endpoint
POST /users
Required Parameters
email
(form-field): The email of the user. It has to be unique.username
(form-field): The username of the user. It has to be unique.
Optional Parameters
can_insert
(form-field): Signifies whether the user has the right to insert content. Possible values aretrue
orfalse
. The default value is set totrue
.role
(form-field): User's role. Possible values areadmin
orbasic
. Rolebasic
allows basic API usage, while roleadmin
allows to modify/delete all content and users. The default value for this attribute is set tobasic
.visibility
(form-field): User's visibility setting. Possible values areprivate
orpublic
. Contents inserted by the user withprivate
visibility setting can only be viewed/searched by this user. Contents inserted by the user withpublic
visibility setting can be viewed/searched by any other user. The default value for this attribute is set topublic
.
Response
The user creation response will return the same information as the Get info about user endpoint for the newly created user. If a user with such username or email already exists, API will return an error message describing conflict type.
Note
You can only create users if you have admin
role.
Note
API automatically generates an API token when creating a user. Remember to provide it to the user so that he can use the API.
Example request:
curl -X POST \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ -F 'email=user1@videntifier.com' \ -F 'username=user1' \ -F 'can_insert=false' \ -F 'role=admin' \ -F 'visibility=private' \ 'https://host.videntifier.com/api/v1/users'
Example response:
{ "data": { "id": "23", "username": "user1", "email": "user1@videntifier.com", "api_token": "iY4bkbEYYDQX31NmWvji", "can_insert": false, "role": "admin", "visibility": "private" } }
Update user information¶
Endpoint
PATCH /users/:id
Required Parameters
None
Note
Even though no parameters are required, one of the optional parameters should always be supplied. On no parameters, you will receive bad request (code 400) HTTP error.
Optional Parameters
can_insert
(form-field): Signifies whether the user has right to insert content. Possible values aretrue
orfalse
.email
(form-field): The email of the user. It has to be unique.role
(form-field): User's role. Possible values areadmin
orbasic
. Rolebasic
allows basic API usage, while roleadmin
allows to modify/delete all content and users.username
(form-field): The username of the user. It has to be unique.visibility
(form-field): User's visibility setting. Possible values areprivate
orpublic
. Contents inserted by the user withprivate
visibility setting can only be viewed/searched by this user. Contents inserted by the user withpublic
visibility setting can be viewed/searched by any other user.
Response
Note
You can only update other users' information if you have admin
role.
If you have basic
role, you can update your own user information, but you cannot change your role.
This endpoint updates attributes of the user specified in the request. Attributes that were not specified will not be updated.
Example request:
curl -X PATCH \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ -F 'email=james@videntifier.com' \ -F 'role=basic' \ 'https://host.videntifier.com/api/v1/users/23'
Example response:
{ "data:": { "message": "User has been updated successfully" } }
Delete user¶
Endpoint
DELETE /users/:id
Required Parameters
None
Optional Parameters
None
Response
Note
You can only delete users if you have admin
role. You can also delete your own account.
Contents inserted by deleted users will not be deleted and will continue to appear in search results unless removed separately (See Delete an image or video).
This endpoint deletes the user using provided user id.
Example request:
curl -X DELETE \ -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/users/23'
Example response:
{ "data:": { "message": "User has been deleted successfully" } }
Get info about user¶
Endpoint
GET /users/:id
Required Parameters
None
Optional Parameters
None
Response
The response lists information about the user. It includes the same fields as described in List users
Example request:
curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/users/23'
Example response:
{ "data": { "id": "23", "username": "user1", "email": "user1@videntifier.com", "api_token": "iY4bkbEYYDQX31NmWvji", "can_insert": false, "role": "admin", "visibility": "private" } }
Get info about database¶
Endpoint
GET /dbinfo
Required Parameters
None
Optional Parameters
None
Response
The response lists information about the database. It has the following fields:
type
: The type of database. Possible values arenvtree
,nvtree-ssd
ornvdb
.nr_points
: Number of visual points stored in the database.nr_scenes
: Number of scenes stored in the database.nr_searches_last_day
: Number of searches performed on the database during the last day.nr_searches_last_hour
: Number of searches performed on the database during the last hour.nr_searches_last_minute
: Number of searches performed on the database during the last minute.nr_threads
: Number of threads the database is using.location
: Database location on the disk.app_version
: Version of the application through which API interacts with the database.db_version
: Version of the database.
Example request:
curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \ 'https://host.videntifier.com/api/v1/dbinfo'
Example response:
{ "data": { "type": "nvtree", "nr_points": "9507666", "nr_scenes": "171", "nr_searches_last_day": "130", "nr_searches_last_hour": "25", "nr_searches_last_minute": "2", "nr_threads": "16", "location": "/home/videntifier/.videntifier/testdatabase", "app_version": "1.0", "db_version": "5.1.0-3a9aa4e" } }
Related matches¶
Related matches are contents that don't match the queried content directly, but are related to it indirectly through the other matched contents. Related matches are found by performing a breadth-first search on the direct matches.
Related matches contain the same content
object as the direct matches (see Query an image or video). However, in addition to the content
object, related matches will have fields with the following extra information:
related_depth
: This field describes the matching distance from the original match. In the provided diagram, related matches of the direct matches haverelated_depth
equal to 1. The contents matching the first depth level of related matches will have a depth equal to 2, and so on.related_content_id
: This field contains a content id of the "parent match", which is a match that resulted in the current related match. In the provided diagram, related matches with a depth of 1 have a content_id of the direct match in therelated_content_id
field.
Searching for related matches immediately returns results when any of the following conditions are met:
- all of the related matches are found
- a matching depth reaches level 6
- total number of the found related matches equals (or exceeds) 100 items
To eliminate low-matching contents, each related match needs to match at least 10% against their parent match (and vice versa, parent match needs to match at least 10%). For example, the related match will not qualify if a very small part of the query image (<10%) matches a large part of the match image.
Note
Related matches are currently only available for the images. Video matches will not result in related matches.