Vionlabs Previews API

Vionlabs API for on-request assembling of previews results.

Get Previews

Deprecated

Authorization

X-API-Key<token>

[DEPRECATED] API key authentication using the X-API-Key HTTP header. Use the 'key' query parameter (?key=YOUR_API_KEY) instead.

In: header

Path Parameters

inventory_id*Inventory Id

Customer identifier for a movie or series item in the catalog

Query Parameters

version?|

Previews version code

clip_type?ClipType

Select specific clip type to search for a specific mood or use any

Default"ANY"

Value in

"A" | "B" | "C" | "D" | "Q1" | "Q2" | "Q3" | "Q4" | "LA" | "HA" | "ANY" | "Funny and comical" | "High-octane action" | "Heartfelt" | "Epic scenery" | "Creepy and scary"

number_of_clips?Number Of Clips

Number of clips to produce. Note if clip criteria are too strict, fewer clips may be returned.

Default5

character?|

Specifies which character(s) the clip should target. Characters are identified by integer ranks, where the main character is 0, secondary is 1 etc. Use CharacterSelector.NONE to allow clips with no criteria for character presence.To get multiple characters, use comma separated values, e.g. 1,2

Default"None"

min_nudity?Min Nudity

Minimum required probability of nudity. Increase this threshold to see clips with more nudity. Introduced in version 8.

Default0

Range0 <= value <= 1

max_nudity?Max Nudity

Maximum allowed probability of nudity in the clips. Introduced in version 8.

Default1

Range0 <= value <= 1

min_profanity?Min Profanity

Minimum required probability of spoken profanity. Introduced in version 8.

Default0

Range0 <= value <= 1

max_profanity?Max Profanity

Maximum allowed probability of spoken profanity in the clips. Introduced in version 8.

Default1

Range0 <= value <= 1

min_brightness?Min Brightness

Minimum allowed brightness in the clips.

Default0

Range0 <= value <= 1

max_brightness?Max Brightness

Maximum allowed brightness in the clips.

Default1

Range0 <= value <= 1

clip_length?Clip Length

Target length of the clips to produce, in seconds. Depending on other parameters, the final length of the clips may deviate from this value.

Default30

skip_start?Skip Start

Prevent clips from being selected from the beginning of the video, expressed as a percentage of video length.

Default10

Range0 <= value <= 100

skip_end?Skip End

Prevent clips from being selected from the end of the video, expressed as a percentage of video length.

Default10

Range0 <= value <= 100

end_bwd_scene_boundary_search?End Bwd Scene Boundary Search

Allow shortening the clip with this many seconds by ending it earlier, if a scene boundary was detected near the end of the clip.

Default0

Range0 <= value

end_fwd_scene_boundary_search?End Fwd Scene Boundary Search

Allow extending the clip with this many seconds by ending it later, if a scene boundary was detected near the end of the clip.

Default0

Range0 <= value

start_bwd_scene_boundary_search?Start Bwd Scene Boundary Search

Allow extending the clip with this many seconds by starting the clip earlier if a scene boundary was detected near the start of the clip.

Default0

Range0 <= value

start_fwd_scene_boundary_search?Start Fwd Scene Boundary Search

Allow shortening the clip with this many seconds by starting the clip later if a scene boundary was detected near the start of the clip.

Default0

Range0 <= value

end_bwd_speech_search?End Bwd Speech Search

Allow shortening the clip with this many seconds by ending it earlier, to avoid the clip ending mid-speech.

Default3

Range0 <= value

end_fwd_speech_search?End Fwd Speech Search

Allow extending the clip with this many seconds by ending the clip later, to avoid the clip ending mid-speech.

Default3

Range0 <= value

end_speech_stop_silence_before?End Speech Stop Silence Before

Defines a margin as to what constitutes as mid-speech at the end of the clip. Require this many seconds of silence before the clip end to be considered safe.

Default0

end_speech_stop_silence_after?End Speech Stop Silence After

Defines a margin as to what constitutes as mid-speech at the end of the clip. Require this many seconds of silence after the clip end to be considered safe.

Default0

start_bwd_speech_search?Start Bwd Speech Search

Allow extending the clip with this many seconds by starting it earlier, to avoid the clip starting mid-speech.

Default1

Range0 <= value

start_fwd_speech_search?Start Fwd Speech Search

Allow shortening the clip with this many seconds by starting it later, to avoid the clip starting mid-speech.

Default1

Range0 <= value

start_speech_stop_silence_before?Start Speech Stop Silence Before

Defines a margin as to what constitutes as mid-speech at the start of the clip. Require this many seconds of silence before the clip start to be considered safe.

Default0.5

start_speech_stop_silence_after?Start Speech Stop Silence After

Defines a margin as to what constitutes as mid-speech at the start of the clip. Require this many seconds of silence after the clip start to be considered safe.

Default0.5

minimum_clip_separation?Minimum Clip Separation

Require this many seconds of separation between clips, in order to distribute the clips across the video and avoid overlaps.

Default60

search_query?|

Search phrase describing the desired content of the clips.

add_keyword_tags?Add Keyword Tags

If True, will add a set of keywords for each clip

Defaulttrue

generate?Generate

Initiate asynchronous process of preview clips extraction

Defaultfalse

Response Body

`application/json`

curl -X GET "https://example.com/results/jitpreviews/v1/string"

{
  "inventory_id": "string",
  "type": "movie",
  "vionlabs_id": "string",
  "version_id": "string",
  "gen_id": "string",
  "jitpreview": [
    {
      "start_time": 0,
      "stop_time": 0,
      "relevance": 0,
      "query_relevance": 0,
      "search_query": "string",
      "start_frame": 0,
      "stop_frame": 0,
      "characters": [],
      "nudity": 0,
      "profanity": 0,
      "brightness": 0,
      "valence": 0,
      "arousal": 0,
      "clip_index": 0,
      "snapped_start": 0,
      "snapped_stop": 0,
      "clip_type": "A",
      "environment": [
        {}
      ],
      "keywords": [
        {}
      ],
      "mood": [
        {}
      ],
      "start_speech_avoidance": 0,
      "end_speech_avoidance": 0,
      "type_score": 0,
      "vionlabs_id": "string",
      "inventory_id": "string",
      "fps": 0,
      "gen": {
        "clip_path": "string",
        "large_image_path": "string",
        "small_image_path": "string"
      }
    }
  ]
}

Empty

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

Get generated preview clips details for gen id

Deprecated

Authorization

X-API-Key<token>

[DEPRECATED] API key authentication using the X-API-Key HTTP header. Use the 'key' query parameter (?key=YOUR_API_KEY) instead.

In: header

Path Parameters

gen_id*Gen Id

Asynchronous gen task identifier

Response Body

`application/json`

curl -X GET "https://example.com/results/jitpreviews/v1/gen/string"

{
  "inventory_id": "string",
  "type": "movie",
  "vionlabs_id": "string",
  "version_id": "string",
  "gen_id": "string",
  "context": {},
  "jitpreview": [
    {
      "start_time": 0,
      "stop_time": 0,
      "start_frame": 0,
      "stop_frame": 0,
      "gen": {
        "clip_path": "string",
        "large_image_path": "string",
        "small_image_path": "string",
        "large_image_width": 0,
        "large_image_height": 0,
        "small_image_width": 0,
        "small_image_height": 0
      }
    }
  ]
}

Empty

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

Get Clip Types Info

Authorization

X-API-Key<token>

[DEPRECATED] API key authentication using the X-API-Key HTTP header. Use the 'key' query parameter (?key=YOUR_API_KEY) instead.

In: header

Query Parameters

version?|

Previews version code

Response Body

`application/json`

curl -X GET "https://example.com/results/jitpreviews/v2/info/clip_types"

{
  "version": "string",
  "clip_types": [
    "string"
  ]
}

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

Get Previews

Authorization

X-API-Key<token>

[DEPRECATED] API key authentication using the X-API-Key HTTP header. Use the 'key' query parameter (?key=YOUR_API_KEY) instead.

In: header

Path Parameters

inventory_id*Inventory Id

Customer identifier for a movie or series item in the catalog

Query Parameters

version?|

Previews version code

character_preference?CharacterPreference

Specifies the preference for the specified character(s) in the clip. Use any to include clips with at least one character. Use None to allow clips without characters. Use avoid to avoid characters. Use any_of to include any of the characters from the character_list. Use all_of to include all of the characters from the character_list.

Default"any"

Value in"any" | "any_of" | "all_of" | "None" | "avoid"

character_list?|

Specifies the list of characters to include in the results when character_preference is set to any_of or all_ofTo select multiple characters, use a comma separated list of integers, e.g. 1,2.

number_of_top_candidates?Number Of Top Candidates

Number of clips to produce. Note if clip criteria are too strict, fewer clips may be returned.

Default5

clip_type?NewClipTypes

Select specific clip type to search for a specific mood. Cannot be used together with search_query unless set to ANY.

Default"ANY"

Value in

"ANY" | "High-octane action" | "Exciting" | "Emotional" | "Dark & gritty" | "Gory & bloody" | "Epic" | "Scary" | "Romantic" | "Funny and comical" | "Heartfelt" | "Epic scenery" | "Creepy and scary"

min_nudity?Min Nudity

Minimum required probability of nudity. Increase this threshold to see clips with more nudity. Introduced in version 8.

Default0

Range0 <= value <= 1

max_nudity?Max Nudity

Maximum allowed probability of nudity in the clips. Introduced in version 8.

Default1

Range0 <= value <= 1

min_profanity?Min Profanity

Minimum required probability of spoken profanity. Introduced in version 8.

Default0

Range0 <= value <= 1

max_profanity?Max Profanity

Maximum allowed probability of spoken profanity in the clips. Introduced in version 8.

Default1

Range0 <= value <= 1

min_brightness?Min Brightness

Minimum allowed brightness in the clips.

Default0

Range0 <= value <= 1

max_brightness?Max Brightness

Maximum allowed brightness in the clips.

Default1

Range0 <= value <= 1

clip_length?Clip Length

Target length of the clips to produce, in seconds. Depending on other parameters, the final length of the clips may deviate from this value.

Default30

Range0 <= value

skip_start?Skip Start

Prevent clips from being selected from the beginning of the video, expressed as a percentage of video length.

Default10

Range0 <= value <= 100

skip_end?Skip End

Prevent clips from being selected from the end of the video, expressed as a percentage of video length.

Default10

Range0 <= value <= 100

start_bwd_snap_search?Start Bwd Snap Search

Allow extending the clip with this many seconds by starting it earlier, if a suitable boundary was detected near the start of the clip.

Default0

start_fwd_snap_search?Start Fwd Snap Search

Allow shortening the clip with this many seconds by starting it later, if a suitable boundary was detected near the start of the clip.

Default0

end_bwd_snap_search?End Bwd Snap Search

Allow shortening the clip with this many seconds by ending it earlier, if a suitable boundary was detected near the end of the clip.

Default0

end_fwd_snap_search?End Fwd Snap Search

Allow extending the clip with this many seconds by ending it later, if a suitable boundary was detected near the end of the clip.

Default0

end_bwd_scene_boundary_search?End Bwd Scene Boundary SearchDeprecated

Allow shortening the clip with this many seconds by ending it earlier, if a scene boundary was detected near the end of the clip.DEPRECATED. Use end_bwd_snap_search instead.

Default0

Range0 <= value

end_fwd_scene_boundary_search?End Fwd Scene Boundary SearchDeprecated

Allow extending the clip with this many seconds by ending it later, if a scene boundary was detected near the end of the clip.DEPRECATED. Use end_fwd_snap_search instead.

Default0

Range0 <= value

start_bwd_scene_boundary_search?Start Bwd Scene Boundary SearchDeprecated

Allow extending the clip with this many seconds by starting the clip earlier if a scene boundary was detected near the start of the clip.DEPRECATED. Use start_fwd_snap_search instead.

Default0

Range0 <= value

start_fwd_scene_boundary_search?Start Fwd Scene Boundary SearchDeprecated

Allow shortening the clip with this many seconds by starting the clip later if a scene boundary was detected near the start of the clip.DEPRECATED. Use start_fwd_snap_search instead.

Default0

Range0 <= value

end_bwd_speech_search?End Bwd Speech Search

Allow shortening the clip with this many seconds by ending it earlier, to avoid the clip ending mid-speech.

Default3

Range0 <= value

end_fwd_speech_search?End Fwd Speech Search

Allow extending the clip with this many seconds by ending the clip later, to avoid the clip ending mid-speech.

Default3

Range0 <= value

end_speech_stop_silence_before?End Speech Stop Silence Before

Defines a margin as to what constitutes as mid-speech at the end of the clip. Require this many seconds of silence before the clip end to be considered safe.

Default0

end_speech_stop_silence_after?End Speech Stop Silence After

Defines a margin as to what constitutes as mid-speech at the end of the clip. Require this many seconds of silence after the clip end to be considered safe.

Default0

start_bwd_speech_search?Start Bwd Speech Search

Allow extending the clip with this many seconds by starting it earlier, to avoid the clip starting mid-speech.

Default1

Range0 <= value

start_fwd_speech_search?Start Fwd Speech Search

Allow shortening the clip with this many seconds by starting it later, to avoid the clip starting mid-speech.

Default1

Range0 <= value

start_speech_stop_silence_before?Start Speech Stop Silence Before

Defines a margin as to what constitutes as mid-speech at the start of the clip. Require this many seconds of silence before the clip start to be considered safe.

Default0.5

start_speech_stop_silence_after?Start Speech Stop Silence After

Defines a margin as to what constitutes as mid-speech at the start of the clip. Require this many seconds of silence after the clip start to be considered safe.

Default0.5

minimum_clip_separation?Minimum Clip Separation

Require this many seconds of separation between clips, in order to distribute the clips across the video and avoid overlaps.

Default60

search_query?|

Search phrase describing the desired content of the clips. Cannot be used together with clip_type unless clip_type is ANY.

add_keyword_tags?Add Keyword Tags

If True, will add a set of keywords for each clip

Defaulttrue

generate?GenerateDeprecated

Initiate asynchronous process of preview clips extraction. Only one of generate or generate_vertical can be True.DEPRECATED. Use trigger_generation instead.

Defaultfalse

generate_vertical?Generate VerticalDeprecated

Initiate asynchronous process of vertical preview clips extraction. Only one of generate or generate_vertical can be True. Only available for product version with vertical prefix.DEPRECATED. Use trigger_generation in conjunction with aspect_ratio instead.

Defaultfalse

trigger_generation?Trigger Generation

Trigger the generation of preview clips.

Defaultfalse

aspect_ratio?AspectRatioSelector

Aspect ratio of the preview clips. When set to 9:16, vertical conversion information is used. Only supported with versions with -vertical suffix.

Default"None"

Value in"None" | "9:16"

custom_start_timestamp?|

Start timestamp in seconds. When provided along with custom_stop_timestamp, returns a single preview clip at the specified time range, skipping the normal candidate discovery. Requires version 19 or higher.

custom_stop_timestamp?|

Stop timestamp in seconds. When provided along with custom_start_timestamp, returns a single preview clip at the specified time range, skipping the normal candidate discovery. Requires version 19 or higher.

Response Body

`application/json`

curl -X GET "https://example.com/results/jitpreviews/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",
    "gen_id": "string",
    "jitpreview": [
      {
        "start_time": 0,
        "stop_time": 0,
        "relevance": 0,
        "query_relevance": 0,
        "search_query": "string",
        "start_frame": 0,
        "stop_frame": 0,
        "characters": [],
        "nudity": 0,
        "profanity": 0,
        "brightness": 0,
        "clip_index": 0,
        "snapped_start": 0,
        "snapped_stop": 0,
        "clip_type": "ANY",
        "environment": [
          {}
        ],
        "keywords": [],
        "keyword": {},
        "mood": [],
        "mood_tag": {},
        "start_speech_avoidance": 0,
        "end_speech_avoidance": 0,
        "type_score": 0,
        "vionlabs_id": "string",
        "inventory_id": "string",
        "fps": 0,
        "gen": {
          "clip_path": "string",
          "large_image_path": "string",
          "small_image_path": "string"
        },
        "vertical_conversion": {
          "coordinates": {
            "property1": 0,
            "property2": 0
          },
          "blackbars": [
            0,
            0
          ],
          "start_buffer": {
            "property1": 0,
            "property2": 0
          },
          "end_buffer": {
            "property1": 0,
            "property2": 0
          }
        },
        "source_frame_width": 0,
        "source_frame_height": 0
      }
    ]
  }
}

Empty

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

Get Genid

Deprecated

Authorization

X-API-Key<token>

[DEPRECATED] API key authentication using the X-API-Key HTTP header. Use the 'key' query parameter (?key=YOUR_API_KEY) instead.

In: header

Path Parameters

gen_id*Gen Id

Asynchronous gen task identifier

Response Body

`application/json`

curl -X GET "https://example.com/results/jitpreviews/v2/gen/string"

{
  "inventory_id": "string",
  "type": "movie",
  "vionlabs_id": "string",
  "version_id": "string",
  "gen_id": "string",
  "context": {},
  "jitpreview": [
    {
      "start_time": 0,
      "stop_time": 0,
      "start_frame": 0,
      "stop_frame": 0,
      "gen": {
        "clip_path": "string",
        "large_image_path": "string",
        "small_image_path": "string",
        "large_image_width": 0,
        "large_image_height": 0,
        "small_image_width": 0,
        "small_image_height": 0
      }
    }
  ]
}

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

Get Genid Status

Authorization

X-API-Key<token>

[DEPRECATED] API key authentication using the X-API-Key HTTP header. Use the 'key' query parameter (?key=YOUR_API_KEY) instead.

In: header

Path Parameters

gen_id*Gen Id

Asynchronous gen task identifier

Response Body

`application/json`

curl -X GET "https://example.com/results/jitpreviews/v2/gen/string/status"

{
  "status": "success",
  "data": {
    "inventory_id": "string",
    "type": "movie",
    "vionlabs_id": "string",
    "version_id": "string",
    "gen_id": "string",
    "context": {},
    "jitpreview": [
      {
        "start_time": 0,
        "stop_time": 0,
        "start_frame": 0,
        "stop_frame": 0,
        "gen": {
          "clip_path": "string",
          "large_image_path": "string",
          "small_image_path": "string",
          "large_image_width": 0,
          "large_image_height": 0,
          "small_image_width": 0,
          "small_image_height": 0
        }
      }
    ]
  }
}

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

Get Vionlabs previews result status

Authorization

X-API-Key<token>

[DEPRECATED] API key authentication using the X-API-Key HTTP header. Use the 'key' query parameter (?key=YOUR_API_KEY) instead.

In: header

Path Parameters

inventory_id*Inventory Id

Customer identifier for a movie or series item in the catalog

Query Parameters

version?|

Previews version code

Response Body

`application/json`

curl -X GET "https://example.com/results/jitpreviews/v2/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"
    }
  ]
}

Get paginated list of the updated inventory_id items with the previews results statuses ordered by creation/update timestamp

Authorization

X-API-Key<token>

[DEPRECATED] API key authentication using the X-API-Key HTTP header. Use the 'key' query parameter (?key=YOUR_API_KEY) instead.

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

Default1000

Range1 <= value

version?|

Previews version code

Response Body

`application/json`

curl -X GET "https://example.com/results/jitpreviews/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

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

Vionlabs Previews API

200application/json

404

422application/json

200application/json

403

404

422application/json

200application/json

422application/json

200application/json

404

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

404

422application/json

200application/json

403

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`