Vionlabs Fingerprint+ API

Fingerprint+ result status and data for an item

Gets fingerprint+ result status and data for an item in the customer catalog.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Path Parameters

inventory_id*Inventory Id

Customer's identifier for a catalog item

Query Parameters

version?|

Specify Fingerprint+ version code

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v3/string"

{
  "status": "success",
  "error": "string",
  "updated": "2019-08-24T14:15:22Z",
  "version_id": "string",
  "inventory_id": "string",
  "type": "movie",
  "data": {
    "inventory_id": "string",
    "type": "movie",
    "vionlabs_id": "string",
    "version_id": "string",
    "fingerprint": [
      0
    ],
    "mood": {
      "High Octane": 1
    },
    "genre": {
      "action": 0.98,
      "martial art": 0.9,
      "thriller": 0.93
    },
    "keyword": {
      "crime boss": 1,
      "crime family": 0.95,
      "crime syndicate": 0.94
    },
    "mood_tag": {
      "revenge": 0.99,
      "suspenseful": 1,
      "violent": 0.99
    },
    "language": {
      "main": "string"
    },
    "synopsis": {
      "synopsis_short": "string",
      "synopsis_long": "string",
      "synopses": {
        "de": {
          "synopsis_short": "string",
          "synopsis_long": "string"
        },
        "en": {
          "synopsis_short": "string",
          "synopsis_long": "string"
        },
        "es": {
          "synopsis_short": "string",
          "synopsis_long": "string"
        },
        "fr": {
          "synopsis_short": "string",
          "synopsis_long": "string"
        },
        "ja": {
          "synopsis_short": "string",
          "synopsis_long": "string"
        },
        "nl": {
          "synopsis_short": "string",
          "synopsis_long": "string"
        },
        "pl": {
          "synopsis_short": "string",
          "synopsis_long": "string"
        },
        "pt": {
          "synopsis_short": "string",
          "synopsis_long": "string"
        },
        "th": {
          "synopsis_short": "string",
          "synopsis_long": "string"
        }
      },
      "error": "string"
    }
  }
}

Empty

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Fingerprint+ result status for an item

Gets fingerprint+ result status for an item in the customer catalog.

This is a lightweight alternative to GET /{inventory_id}, intended for polling whether a result is ready (success/failed). It returns only the status fields, omitting the full Fingerprint+ data payload, which keeps responses small and easy to parse when the result data itself is not needed.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Path Parameters

inventory_id*Inventory Id

Customer's identifier for a catalog item

Query Parameters

version?|

Specify Fingerprint+ version code

Response Body

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v3/status/string"

{
  "status": "success",
  "error": "string",
  "updated": "2019-08-24T14:15:22Z",
  "version_id": "string",
  "inventory_id": "string",
  "type": "movie"
}

Empty

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Paginated Fingerprint+ results

Gets a paginated list of items with Fingerprint+ results statuses and data for the customer catalog.

The parameters from_utcdatetime and to_utcdatetime filter by the moment when processing of the Fingerprint+ product finished for an asset (UTC timestamps).

Example: To retrieve items whose processing finished between 2024-03-06T20:00:00 and 2024-03-07T20:00:00, call the endpoint with: from_utcdatetime=2024-03-06T20:00:00&to_utcdatetime=2024-03-07T20:00:00.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Query Parameters

from_utcdatetime?|

Specifies the start of the UTC time window (ISO 8601) for items whose Fingerprint+ processing finished at or after this time. If not specified then all results will be returned

to_utcdatetime?|

Specifies the end of the UTC time window (ISO 8601) for items whose Fingerprint+ processing finished at or before this time. If not specified then utcnow() value will be used. It is recommended to fix this argument while looping across pages to establish a fixed time window

page_num?Page Num

Specifies a positional number of page with results

Default0

Range0 <= value

page_size?Page Size

Specifies a max number of results per page

Default500

Range1 <= value

type?AssetTypeSelector

Specify type of assets

Default"all"

Value in

"all" | "movie" | "series" | "seasons" | "series_and_episodes" | "seasons_and_episodes" | "series_and_seasons_and_episodes" | "movie_and_series"

version?|

Specifies Fingerprint+ version code

Response Body

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v3/"

{
  "page_num": 0,
  "page_size": 0,
  "total_count": 0,
  "data": []
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get Vocabularies

Gets vocabularies for all components (moods, genres, keywords, mood_tags) associated with a specific Fingerprint+ version.

Note: the keyword vocabulary is only the core set. The system can also produce keywords outside this vocabulary, so results may contain keywords that are not listed here.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Query Parameters

version?|

Fingerprint+ version code

Response Body

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v3/metadata/vocabularies"

{
  "version": "11.7",
  "mood": [
    "Cerebral Thrills",
    "Dark & Gritty",
    "Heartwarming Family",
    "Love & Romance",
    "Uplifting & Feelgood"
  ],
  "genre": [
    "action",
    "drama",
    "comedy",
    "thriller"
  ],
  "keyword": [
    "car chase",
    "romance",
    "explosion",
    "dialogue"
  ],
  "moodtag": [
    "atmospheric",
    "dark",
    "feel-good",
    "intense",
    "moody",
    "suspenseful",
    "tense",
    "uplifting"
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get Similar Titles

Get a list of similar items to the specified customer inventory id from the customer catalog. Use the asset_type query parameter to filter by movies, series, or both (default). Query parameters skip and count can be used to accumulate longer lists over multiple calls.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Path Parameters

inventory_id*Inventory Id

Customer's identifier for a catalog item

Query Parameters

asset_type?|

Type of similar items to return. If not specified, all types are returned

version?|

Specify Fingerprint+ version for the similarity lists

skip?|

Number of items to skip from beginning of list

count?|

Number of items to return in list

Response Body

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v3/similar/string"

{
  "inventory_id": "string",
  "type": "movie",
  "vionlabs_id": "string",
  "last_updated": "2019-08-24T14:15:22Z",
  "version_id": "string",
  "similar": [
    {
      "inventory_id": "string",
      "type": "movie",
      "vionlabs_id": "string",
      "score": 0
    }
  ]
}

Empty

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Discover similar titles from the Global Fingerprint Platform (GFP)

Get similar titles from the Global Fingerprint Platform based on a title from the customer catalog. The Global Fingerprint Platform contains titles from across the Vionlabs content universe, not limited to the customer's own catalog. This endpoint helps customers discover content they might not own that is similar to content that is popular on their platform.

This endpoint is experimental and subject to change - please contact Vionlabs before using in Production workflows.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Path Parameters

inventory_id*Inventory Id

Customer's identifier for a catalog item

Query Parameters

version?|

Specify Fingerprint+ version for the query title embedding

count?Count

Number of items to return in list.

Default50

Range1 <= value <= 75

Response Body

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v3/similar/gfp/string"

{
  "similar": [
    {
      "type": "string",
      "imdb_id": "string",
      "title": "string",
      "year": 0,
      "score": 0
    }
  ]
}

Empty

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Fingerprint+ result status and data for an item (localized)

Gets fingerprint+ result status and data for an item in the customer catalog, with vocabulary labels and synopsis returned in the requested language.

Editorial tag edits apply only to the language they were made in, so the tag sets returned for two languages are not necessarily translations of each other.

The fingerprint (embedding) is no longer included in this response; it is available from the dedicated GET /{inventory_id}/fingerprint endpoint.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Path Parameters

inventory_id*Inventory Id

Customer's identifier for a catalog item

Query Parameters

version?|

Specify Fingerprint+ version code

language?Language

ISO 639-1 language code for vocabulary labels and synopsis

Default"en"

Value in"de" | "en" | "es" | "fr" | "ja" | "nl" | "pl" | "pt" | "th"

Response Body

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v4/string"

{
  "status": "success",
  "error": "string",
  "updated": "2019-08-24T14:15:22Z",
  "version_id": "string",
  "inventory_id": "string",
  "type": "movie",
  "data": {
    "inventory_id": "string",
    "type": "movie",
    "vionlabs_id": "string",
    "version_id": "string",
    "mood": {
      "property1": 0,
      "property2": 0
    },
    "genre": {
      "property1": 0,
      "property2": 0
    },
    "keyword": {
      "property1": 0,
      "property2": 0
    },
    "mood_tag": {
      "property1": 0,
      "property2": 0
    },
    "language": {
      "main": "string"
    },
    "synopsis": {
      "synopsis_short": "string",
      "synopsis_long": "string",
      "error": "string"
    }
  }
}

Empty

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Fingerprint+ embedding for an item

Gets the fingerprint (embedding) vector for an item in the customer catalog.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Path Parameters

inventory_id*Inventory Id

Customer's identifier for a catalog item

Query Parameters

version?|

Specify Fingerprint+ version code

Response Body

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v4/string/fingerprint"

{
  "inventory_id": "string",
  "type": "movie",
  "vionlabs_id": "string",
  "version_id": "string",
  "fingerprint": [
    0
  ]
}

Empty

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Paginated Fingerprint+ results (localized)

Gets a paginated list of items with Fingerprint+ results statuses and data for the customer catalog, localized to the requested language.

Editorial tag edits apply only to the language they were made in, so the tag sets returned for two languages are not necessarily translations of each other.

The parameters from_utcdatetime and to_utcdatetime filter by the moment when processing of the Fingerprint+ product finished for an asset (UTC timestamps).

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Query Parameters

from_utcdatetime?|

Specifies the start of the UTC time window (ISO 8601) for items whose Fingerprint+ processing finished at or after this time. If not specified then all results will be returned

to_utcdatetime?|

page_num?Page Num

Specifies a positional number of page with results

Default0

Range0 <= value

page_size?Page Size

Specifies a max number of results per page

Default500

Range1 <= value

type?AssetTypeSelector

Specify type of assets

Default"all"

Value in

"all" | "movie" | "series" | "seasons" | "series_and_episodes" | "seasons_and_episodes" | "series_and_seasons_and_episodes" | "movie_and_series"

version?|

Specifies Fingerprint+ version code

language?Language

ISO 639-1 language code for vocabulary labels and synopsis

Default"en"

Value in"de" | "en" | "es" | "fr" | "ja" | "nl" | "pl" | "pt" | "th"

Response Body

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v4/"

{
  "page_num": 0,
  "page_size": 0,
  "total_count": 0,
  "data": []
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get Vocabularies

Gets vocabularies for all components (moods, genres, keywords, mood_tags) associated with a specific Fingerprint+ version, in the requested language.

Note: the keyword vocabulary is only the core set. The system can also produce keywords outside this vocabulary, so results may contain keywords that are not listed here.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Query Parameters

version?|

Fingerprint+ version code

language?Language

ISO 639-1 language code for vocabulary labels

Default"en"

Value in"de" | "en" | "es" | "fr" | "ja" | "nl" | "pl" | "pt" | "th"

Response Body

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v4/metadata/vocabularies"

{
  "version": "11.7",
  "language": "en",
  "mood": [
    "string"
  ],
  "genre": [
    "string"
  ],
  "keyword": [
    "string"
  ],
  "moodtag": [
    "string"
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get Similar Titles

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Path Parameters

inventory_id*Inventory Id

Customer's identifier for a catalog item

Query Parameters

asset_type?|

Type of similar items to return. If not specified, all types are returned

version?|

Specify Fingerprint+ version for the similarity lists

skip?|

Number of items to skip from beginning of list

count?|

Number of items to return in list

Response Body

`application/json`

curl -X GET "https://example.com/results/fingerprintplus/v4/string/similar"

{
  "inventory_id": "string",
  "type": "movie",
  "vionlabs_id": "string",
  "last_updated": "2019-08-24T14:15:22Z",
  "version_id": "string",
  "similar": [
    {
      "inventory_id": "string",
      "type": "movie",
      "vionlabs_id": "string",
      "score": 0
    }
  ]
}

Empty

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Vionlabs Fingerprint+ API

200application/json

403

404

422application/json

200application/json

403

404

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

403

404

422application/json

200application/json

403

404

422application/json

200application/json

403

404

422application/json

200application/json

403

404

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

403

404

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`