Vertx API

One can search and register multimedia content through the Vertx API in a number of different ways:

Calling Vertx REST API;
Using Vertx command line utility (Vertx CLI);
Running Vertx CLI wrapped into a Docker container;
iOS and Android SDKs.

A valid API key is required to make any API calls. To get one, follow the registration procedure at https://portal.vertx.ai. Export your secret API key as VERTX_API_KEY environmental variable:

export VERTX_API_KEY="YOUR VERTX API KEY"

REST API

The simplest way to start using Vertx technology is through the REST API. One can call REST API either by making requests from the Playground page or using command line utilities like curl. Follow this one-minute video tutorial on how to play with the API directly from your browser in the Playground.

The media content is being uploaded to the Vertx Backend when calling REST API. Digital fingerprints are extracted from the uploaded content and are matched against reference databases.

One can also use a command line utility like curl to directly call Vertx REST API. API key should be provided in the X-Session-Token header. The command to find matches for sample.mp4 in the public bucket is provided below:

curl -X POST "https://api.vertx.ai/v1/search/" \
  -H "X-Session-Token: ${VERTX_API_KEY}" \
  -F "media_file=@/path/to/sample.mp4" 

Vertx Command Line Utility

One can also use Vertx command line utility to make API calls. It employs edge computing to extract signatures from media content and uploads only digital fingerprints to the Vertx Backend.

The latest binary for Linux x86-64 platform can be downloaded from the Github releases page. The command to find matches for sample.mp4 in the public bucket is provided below:

vertx search sample.mp4

Docker

One can also use the provided docker container image to run Vertx command line utility on the platforms where it is not available yet.

Install docker container engines for your operating system.
Run the following command to perform content-based search providing sample.mp4 located in the current directory as input:

docker run \
  --rm vertxai/vertx_cli:latest \
  -v $(pwd)/sample.mp4:/data/sample.mp4 \
  -e VERTX_API_KEY=${VERTX_API_KEY} \
  /app/vertx search /data/sample.mp4

The command will download the latest container image with the Vertx command line utility and run the container.

Vertx Search result

Vertx search results are delivered in JSON format. Each result contains the following JSON fields:

media_content indicates type of the content being searched (audio or video);
source_path - path of the source (query);
source_uid - unique identifier of the source (query);
status - status of the search call ("OK" if succeeded).
error - detailed error message if call failed.
request_id - unique identifier of the request.
duration - duration (in seconds) of the source (query);

Each result also contains an array of matches.

A match contains metadata information for the reference content and a list of segments.

Metadata section has the following properties:

bucket - content bucket reference content belongs to (for example, "movies" or "music");
title - title of the reference content (track or movie title);
uid - a unique identifier of the reference content;
cover_url - cover art image URL relative to https://static.vertx.ai;
extra - extra information that does not fall into any other category.
duration - duration (in seconds) of the reference content;

Metadata properties specific to movies:

imdb_id - IMDB identifier of the reference movie;
year - release year of the movie.

Metadata properties specific to music:

artist - artist;
album - album.

Each segment contains the following information:

duration - duration (in seconds) of the match segment;
que_offset - the offset to the match segment in the input (query) file (in seconds);
ref_offset - the offset to the match segment in the reference item (in seconds).

The resulting JSON response for the sample.mp4 request media file would look like:

[
  {
    "duration": 24.9375,
    "error": null,
    "matches": [
      {
        "metadata": {
          "album": null,
          "artist": null,
          "bucket": "movies",
          "cover_url": "/assets/images/movies/you_got_served_2004/large-cover.jpg",
          "duration": 5674.875,
          "extra": null,
          "imdb_id": 365957,
          "title": "You Got Served",
          "uid": "1566530810344932800",
          "year": 2004
        },
        "segments": [
          {
            "duration": 24.875,
            "que_offset": 0.0,
            "ref_offset": 3500.6875
          }
        ]
      },
      {
        "metadata": {
          "album": "Elephunk",
          "artist": "Black Eyed Peas; Papa Roach",
          "bucket": "music",
          "cover_url": null,
          "duration": 218.5,
          "extra": null,
          "imdb_id": null,
          "title": "Anxiety",
          "uid": "6475547275973858650",
          "year": null
        },
        "segments": [
          {
            "duration": 24.875,
            "que_offset": 0.0,
            "ref_offset": 18.125
          }
        ]
      }
    ],
    "media_type": "audio",
    "request_id": "1c984237-2b1a-4c0d-a54c-e299d99a616b",
    "source_path": "./sample.mp4",
    "source_uid": "1758730481226206085",
    "status": "OK"
  },
  {
    "duration": 24.9375,
    "error": null,
    "matches": [
      {
        "metadata": {
          "album": null,
          "artist": null,
          "bucket": "movies",
          "cover_url": "/assets/images/movies/Troy_2004/large-cover.jpg",
          "duration": 11148.0,
          "extra": null,
          "imdb_id": 332452,
          "title": "Troy",
          "uid": "1342729426672482861",
          "year": 2004
        },
        "segments": [
          {
            "duration": 21.625,
            "que_offset": 0.0,
            "ref_offset": 8608.5625
          }
        ]
      }
    ],
    "media_type": "video",
    "request_id": "1c984237-2b1a-4c0d-a54c-e299d99a616b",
    "source_path": "./sample.mp4",
    "source_uid": "1758730481226206085",
    "status": "OK"
  }
]

The content from sample.mp4 file matched with three items from the public bucket. Video content matched with the "Troy" movie, while audio content matched with the "Anxiety" music track by "Black Eyed Peas" and "Papa Roach". The song was also used as a soundtrack in "You Got Served" movie. Vertx was able to successfully identify all the matching segments, both audio and video.

Rate limiting

REST API the following limitations:

5 API calls per 10 seconds;
Max uploaded file size is 100 MB;
Max analyzed media content length is 600 seconds;

For higher quotas limits and extended functionality please Contact us.

Vertx API

REST API​

Vertx Command Line Utility​

Docker​

Vertx Search result​

Rate limiting

REST API

Vertx Command Line Utility

Docker

Vertx Search result