Vionlabs Docs
API Specs

Vionlabs Contextual Ad Breaks API

External docs:SwaggerReDoc

Get item Contextual Ad Breaks result status and data

Deprecated
GET
/results/contextual_adbreak/v2/{inventory_id}

Get Contextual Ad Break 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 identifier of the asset in the catalog

Query Parameters

version?|

Contextual Ad Break results version code

minimum_separation?Minimum Separation

A number of minutes of minimum separation between Ad Breaks

Default1
maximum_separation?Maximum Separation

A number of minutes of maximum separation between Ad Breaks

Default5
skip_first?Skip First

A number of first minutes to skip checking for an Ad Break presence

Default1
skip_last?Skip Last

A number of last minutes to skip checking for an Ad Break presence

Default1

Response Body

application/json

application/json

curl -X GET "https://example.com/results/contextual_adbreak/v2/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",
    "context_adbreak": [
      {
        "timestamp": 0,
        "frame_number": 0,
        "rank": 1,
        "contains_nudity": true,
        "contains_profanity": true,
        "contains_gore": true,
        "keyword": {
          "home invasion": 0.6720908284187317,
          "house": 0.8338738679885864
        },
        "environment_tag": {
          "city street": 1,
          "urban plaza": 1
        },
        "mood_tag": {
          "amusing": 0.7611500024795532,
          "suspenseful": 0.5756270885467529
        },
        "iab_version": "3.0",
        "iab_tier": {
          "Home Appliances": 0.3063124120235443,
          "Home Entertaining": 0.3500327467918396,
          "Home Improvement": 0.3170643746852875,
          "Home Security": 0.32824498414993286,
          "Houses": 0.4657664895057678,
          "Smart Home": 0.3314751386642456,
          "Special Interest  Indie or Art House": 0.3367156684398651
        },
        "iab_uid": {
          "326": 0.3500327467918396,
          "665": 0.4657664895057678,
          "712": 0.3314751386642456,
          "743": 0.32824498414993286,
          "788": 0.3367156684398651,
          "809": 0.3170643746852875,
          "833": 0.3063124120235443
        },
        "iab_all_versions": {
          "2.0": {
            "iab_tier": {
              "Remodeling & Construction": 0.56,
              "Utility/Online Tool": 0.58
            },
            "iab_uid": {
              "276": 0.56,
              "1008": 0.58
            }
          },
          "2.2": {
            "iab_tier": {
              "Remodeling & Construction": 0.56,
              "Utility/Online Tool": 0.58
            },
            "iab_uid": {
              "276": 0.56,
              "1008": 0.58
            }
          },
          "3.0": {
            "iab_tier": {
              "Interior Decorating": 0.47,
              "Remodeling & Construction": 0.56
            },
            "iab_uid": {
              "276": 0.56,
              "283": 0.47
            }
          }
        }
      }
    ]
  }
}
Empty
Empty
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get item Contextual Ad Breaks result status

Deprecated
GET
/results/contextual_adbreak/v2/status/{inventory_id}

Get Contextual Ad Break result status 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 identifier of the asset in the catalog

Query Parameters

version?|

Contextual Ad Break results version code

Response Body

application/json

application/json

curl -X GET "https://example.com/results/contextual_adbreak/v2/status/string"
{
  "status": "success",
  "error": "string",
  "updated": "2019-08-24T14:15:22Z",
  "version_id": "string",
  "inventory_id": "string",
  "type": "movie"
}
Empty
Empty
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get paginated list of items with Contextual Ad Breaks results statuses and data ordered by creation/update timestamp

Deprecated
GET
/results/contextual_adbreak/v2/

Gets paginated list of items with Contextual Ad Breaks results statuses for 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

Query Parameters

from_utcdatetime?|

Specifies start of time window (ISO 8601). If not specified then all results will be returned

to_utcdatetime?|

Specifies end of time window (ISO 8601). 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 result version code

Response Body

application/json

application/json

curl -X GET "https://example.com/results/contextual_adbreak/v2/"
{
  "page_num": 0,
  "page_size": 0,
  "total_count": 0,
  "data": [
    {
      "status": "success",
      "error": "string",
      "updated": "2019-08-24T14:15:22Z",
      "version_id": "string",
      "inventory_id": "string",
      "type": "movie"
    }
  ]
}
Empty
Empty
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get item Contextual Ad Breaks result status and data

GET
/results/contextual_adbreak/v3/{inventory_id}

Get Contextual Ad Breaks for an item in the customer catalog.

Returns the full contextual data, including rank, label, timing information, and metadata. The skip_first and skip_last parameters exclude ad breaks near the start and end of the content, in minutes. minimum_separation drops items that are closer than the requested gap. Ranks do not affect this filtering.

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 identifier of the asset in the catalog

Query Parameters

version?|

Contextual Ad Break results version code

minimum_separation?Minimum Separation

Minimum separation between ad breaks in minutes. Breaks closer than this are dropped. 0 means no filtering.

Default0
skip_first?Skip First

Number of minutes at the start of the content to exclude ad breaks from. 0 means no skipping.

Default0
skip_last?Skip Last

Number of minutes at the end of the content to exclude ad breaks from. 0 means no skipping.

Default0

Response Body

application/json

application/json

curl -X GET "https://example.com/results/contextual_adbreak/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",
    "context_adbreak": [
      {
        "timestamp": 0,
        "frame_number": 0,
        "rank": 1,
        "contains_nudity": true,
        "contains_profanity": true,
        "contains_gore": true,
        "keyword": {
          "home invasion": 0.6720908284187317,
          "house": 0.8338738679885864
        },
        "environment_tag": {
          "city street": 1,
          "urban plaza": 1
        },
        "mood_tag": {
          "amusing": 0.7611500024795532,
          "suspenseful": 0.5756270885467529
        },
        "iab_version": "3.0",
        "iab_tier": {
          "Home Appliances": 0.3063124120235443,
          "Home Entertaining": 0.3500327467918396,
          "Home Improvement": 0.3170643746852875,
          "Home Security": 0.32824498414993286,
          "Houses": 0.4657664895057678,
          "Smart Home": 0.3314751386642456,
          "Special Interest  Indie or Art House": 0.3367156684398651
        },
        "iab_uid": {
          "326": 0.3500327467918396,
          "665": 0.4657664895057678,
          "712": 0.3314751386642456,
          "743": 0.32824498414993286,
          "788": 0.3367156684398651,
          "809": 0.3170643746852875,
          "833": 0.3063124120235443
        },
        "iab_all_versions": {
          "2.0": {
            "iab_tier": {
              "Remodeling & Construction": 0.56,
              "Utility/Online Tool": 0.58
            },
            "iab_uid": {
              "276": 0.56,
              "1008": 0.58
            }
          },
          "2.2": {
            "iab_tier": {
              "Remodeling & Construction": 0.56,
              "Utility/Online Tool": 0.58
            },
            "iab_uid": {
              "276": 0.56,
              "1008": 0.58
            }
          },
          "3.0": {
            "iab_tier": {
              "Interior Decorating": 0.47,
              "Remodeling & Construction": 0.56
            },
            "iab_uid": {
              "276": 0.56,
              "283": 0.47
            }
          }
        }
      }
    ]
  }
}
Empty
Empty
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get item Contextual Ad Breaks result status

GET
/results/contextual_adbreak/v3/status/{inventory_id}

Get the Contextual Ad Break processing status for an item without fetching the full payload. Useful for lightweight polling before calling the main GET /{inventory_id} 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 identifier of the asset in the catalog

Query Parameters

version?|

Contextual Ad Break results version code

Response Body

application/json

application/json

curl -X GET "https://example.com/results/contextual_adbreak/v3/status/string"
{
  "status": "success",
  "error": "string",
  "updated": "2019-08-24T14:15:22Z",
  "version_id": "string",
  "inventory_id": "string",
  "type": "movie"
}
Empty
Empty
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get paginated list of items with Contextual Ad Breaks results statuses ordered by creation/update timestamp

GET
/results/contextual_adbreak/v3/

Get a paginated list of inventory items that have Contextual Ad Breaks results, ordered by creation/update timestamp. Use to bulk-pull newly processed assets.

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?|

Start of time window (ISO 8601). If omitted all results are returned.

to_utcdatetime?|

End of time window (ISO 8601). Defaults to utcnow(). Fix this value while paginating to keep the window stable.

page_num?Page Num

Zero-based page number

Default0
Range0 <= value
page_size?Page Size

Max 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?|

Contextual Ad Break results version code

Response Body

application/json

application/json

curl -X GET "https://example.com/results/contextual_adbreak/v3/"
{
  "page_num": 0,
  "page_size": 0,
  "total_count": 0,
  "data": [
    {
      "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"
    }
  ]
}

Vionlabs Ad Breaks API

Vionlabs API for retrieval of adbreaks results. **Note:** The Ad Breaks product has been discontinued. Customers are encouraged to explore the Contextual Ad Breaks API (`/results/contextual_adbreak`), which is a superset of Ad Breaks.

Vionlabs Thumbnails API

Vionlabs API for on-request assembling of thumbnails results.