Skip to main content
Documentation Powered by Redocly

Vertx API (1.0.0)

Introduction

Vertx provides a simple and powerful REST API to manage signatures and metadata for multimedia content. It also exposes API to perform content-based search in large multimedia collections.

This API reference provides information on available endpoints and how to interact with it. To read more about the API, visit our API Documentation.

Vertx Technology

Overview

System Architecture

Overview

Vertx technology facilitates reverse audio/video search at a large scale. It works amazingly fast, allowing one to identify any piece of content within a blink of an eye. Check out this YouTube video that was captured using a cellphone camera pointed at a TV screen running "Troy" movie and some music in the background.

alt text

Vertx is able to scan the audio and video content of the clip against multimedia databases containing millions of songs and thousands of movies and identify all the matches in a second.

The video file sample.mp4 will be used in API search request examples throughout the rest of the documentation and can be downloaded following this direct link.

System Architecture

Vertx technology is based on extracting digital signatures from audio and video content (also called digital fingerprints) and adding them to a searchable indices. Much likely like human fingerprints, digital fingerprints uniquely identify a chunk of audio/video content. Fingerprint is a highly compressed representation of the mutimedia content if compared to the original audio/video signals. It's not possible to restore the original content from digital fingerprints.

The three main components of the Vertx ecosystem are Vertx Cloud, Vertx Backend and Vertx Clients.

alt text

Vertx Cloud stores indices of the reference content and serves search and registration requests from Vertx Backend. Vertx Clients can upload media content for signature registration to the Vertx Backend servers through the REST API.

When using Vertx command line utility, fingerprint extraction happens on the client side and no original media content is being uploaded. Only extracted fingerprints are sent to the Vertx backend servers for search or registration.

All the reference content in the Vertx Cloud is organized into buckets. Buckets can be private or public. There are two public buckets: music and movies. They contain fingerprints for millions of songs and thousands of movies. Private buckets contain content registered by an organization (owner) and can only be accessed and managed by the owner.

Authentication

When you sign up for an account, you are given your secret API key. You authenticate to the Vertx API by providing your secret key in the X-Session-Token request header.

Never share your secret keys. Keep them guarded and secure.

ApiKeyAuth

Security Scheme Type: API Key
Header parameter name: X-Session-Token

Interacting with the API

Status codes

  • 200 OK Successful request.
  • 400 Bad Request Returns JSON with the error message.
  • 401 Unauthorized Couldn’t authenticate your request.
  • 404 Not Found No such object.
  • 429 Too Many Requests Your connection is being rate limited.
  • 500 Internal Server Error Something went wrong.
  • 503 Service Unavailable Your connection is being throttled or the service is down for maintenance.

Making requests

As per RESTful design patterns, Vertx API implements the following HTTP verbs:

  • GET - Read resources
  • POST - Create new resources or modify existing resources
  • DELETE - Remove resources

When making requests, arguments can be passed as params, form data or JSON with correct Content-Type header.

CORS

Vertx API v1 supports cross-origin HTTP requests which is commonly referred as CORS. This means that you can call API resources using Javascript from any browser. While this allows many interesting use cases, it’s important to remember that you should never expose private API keys to 3rd parties.

Pagination

All GET endpoints which return an object list support cursor based pagination with pagination information inside a pagination object. This means that to get all objects, you need to paginate through the results by always using the id of the last resource

in the list as a GET parameter for the next call. To make it easier, the API will construct the next call into next uri together with all the currently used pagination parameters. You know that you have paginated all the results when the response’s next uri is empty. Default limit is set to 50 but values up to 100 are permitted. Due to permissions and access level control, the response list might in some cases return less objects than specified by the limit parameter. This is normal behaviour and should be expected.

Calling Vertx API using Vertx command-line utility

In addition to the REST API, one can use Vertx command-line utility to manipulate multimedia signatures and metadata and make search requests.

Vertx CLI supports authentication with api key passed as environmental variable VERTX_API_KEY: 

VERTX_API_KEY=<YOUR_VERTX_API_KEY> vertx

Getting started guide

Vertx API is a very simple but powerful API. It allows you to insert, update, delete, and list signatures and metadata for multimedia asset. It also enables you to search in the large-scale database of reference content.
That's more than you'll need to implement your use cases. If you have a use case you would like to implement, please consult us for feedback on the best API operations for the task.

Search

Content-based search of {media_file}. By default, search is performed in public buckets, containing content from movies and music buckets. Searching in custom buckets can be performed if {bucket} is specified.

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
media_file
required
string <binary>
buckets
string or null^[0-9a-z_\-\,]{1,150}$
Default: "public"

Comma-separated list of search buckets. By default, search is performed in public bucket containing music and movies.

media_type
string or null
Default: "all"
Enum: "audio" "video" "all"

Media type of the content to be searched (audio, video, all)

Responses

Request samples 

curl --location --request POST "https://api.vertx.ai/v1/search" \
--header "X-Session-Token: ${VERTX_API_KEY}" \
--form 'media_file=@/path/to/sample.mp4' \
--form 'buckets="music,movies"' \
--form 'media_type="all"'

Response samples

Content type
application/json
[
  • {
    }
]

List media assets

Retrieve a list of media assets registered in bucket {bucket}

Authorizations:
ApiKeyAuth
path Parameters
bucket
required
string^[0-9a-z_\-]{1,50}$

Content bucket

query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 50

The number of items to return in a single request

page[after]
string

URI to the next page

Responses

Request samples 

curl "https://api.vertx.ai/v1/media/${BUCKET}?page[size]=50&page[after]=" \
  --header "X-Session-Token: ${VERTX_API_KEY}"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Register media asset

Add signatures and metadata for media asset file {media_file} to content bucket {bucket}. Attach corresponding {metadata} in JSON format.

Authorizations:
ApiKeyAuth
path Parameters
bucket
required
string^[0-9a-z_\-]{1,50}$

Content bucket

Request Body schema: multipart/form-data
media_file
required
string <binary>

Binary content of a media file to register

metadata
required
string

Metadata in JSON format

media_type
string or null
Default: "all"
Enum: "audio" "video" "all"

Media type of the content to be registered (audio, video, all)

Responses

Request samples 

curl -X POST "https://api.vertx.ai/v1/media/${BUCKET}" \
  --header "X-Session-Token: ${VERTX_API_KEY}" \
  -F media_file="@sample.mp4" \
  -F metadata='{"album": "sample_album", "artist": "sample_artist", "cover_url": "/images/cover.jpg", "extra": "extra_meta", "imdb_id": 4423, "title": "sample_title", "year": 2004}' \
  -F media_type="all"

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve media asset

Retrieve metadata for media asset with UID {uid} registered in bucket {bucket}.

Authorizations:
ApiKeyAuth
path Parameters
bucket
required
string^[0-9a-z_\-]{1,50}$

Content bucket

uid
required
string (MediaUID) ^[0-9]{1,20}$
Example: 1758730481226206085

Unique identifier of media asset to retrieve

Responses

Request samples 

curl "https://api.vertx.ai/v1/media/${BUCKET}/1758730481226206085" \
  --header "X-Session-Token: ${VERTX_API_KEY}"

Response samples

Content type
application/json
{
  • "uid": "1758730481226206085",
  • "bucket": "music",
  • "title": "Tell Me Why",
  • "year": 1984,
  • "imdb_id": 332452,
  • "album": "A Hard Day's Night",
  • "artist": "The Beatles",
  • "cover_url": "/assets/images/movies/Troy_2004/large-cover.jpg",
  • "extra": "{\"custom_field\": \"custom_value\"}",
  • "duration": 17.3
}

Update media asset

Update metadata for media asset with UID {uid} registered in bucket {bucket}.

Authorizations:
ApiKeyAuth
path Parameters
bucket
required
string^[0-9a-z_\-]{1,50}$

Content bucket

uid
required
string (MediaUID) ^[0-9]{1,20}$
Example: 1758730481226206085

Unique identifier of media asset to update

Request Body schema: multipart/form-data
metadata
required
string <binary>

Responses

Request samples 

curl -X POST "https://api.vertx.ai/v1/media/${BUCKET}/1758730481226206085" \
  --header "X-Session-Token: ${VERTX_API_KEY}" \
  --form metadata='{"title"="new_title"}'

Response samples

Content type
application/json
{
  • "uid": "1758730481226206085",
  • "bucket": "music",
  • "title": "Tell Me Why",
  • "year": 1984,
  • "imdb_id": 332452,
  • "album": "A Hard Day's Night",
  • "artist": "The Beatles",
  • "cover_url": "/assets/images/movies/Troy_2004/large-cover.jpg",
  • "extra": "{\"custom_field\": \"custom_value\"}",
  • "duration": 17.3
}

Delete media asset

Delete signatures and metadata for media asset with UID {uid} registered in bucket {bucket}.

Authorizations:
ApiKeyAuth
path Parameters
bucket
required
string^[0-9a-z_\-]{1,50}$

Content bucket

uid
required
string (MediaUID) ^[0-9]{1,20}$
Example: 1758730481226206085

Unique identifier of media asset to update

Responses

Request samples 

curl -X DELETE "https://api.vertx.ai/v1/media/${BUCKET}/1758730481226206085" \
  --header "X-Session-Token: ${VERTX_API_KEY}"