Vionlabs Previews API

Vionlabs API for on-request assembling of previews results.

Get Previews

Get previews for an item in the customer catalog (movie or series)

Path Parameters

inventory_idInventory Id

Customer identifier for a movie or series item in the catalog

Query Parameters

version?Version

Previews version code

clip_type?ClipType

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

Default"ANY"

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

curl -X GET "https://loading/results/jitpreviews/v1/string?version=string&clip_type=ANY&number_of_clips=5&character=None&min_nudity=0&max_nudity=1&min_profanity=0&max_profanity=1&min_brightness=0&max_brightness=1&clip_length=30&skip_start=10&skip_end=10&end_bwd_scene_boundary_search=0&end_fwd_scene_boundary_search=0&start_bwd_scene_boundary_search=0&start_fwd_scene_boundary_search=0&end_bwd_speech_search=3&end_fwd_speech_search=3&end_speech_stop_silence_before=0&end_speech_stop_silence_after=0&start_bwd_speech_search=1&start_fwd_speech_search=1&start_speech_stop_silence_before=0.5&start_speech_stop_silence_after=0.5&minimum_clip_separation=60&search_query=Dystopian+environment&add_keyword_tags=true&generate=false"

curl -X GET "https://loading/results/jitpreviews/v1/string?version=string&clip_type=ANY&number_of_clips=5&character=None&min_nudity=0&max_nudity=1&min_profanity=0&max_profanity=1&min_brightness=0&max_brightness=1&clip_length=30&skip_start=10&skip_end=10&end_bwd_scene_boundary_search=0&end_fwd_scene_boundary_search=0&start_bwd_scene_boundary_search=0&start_fwd_scene_boundary_search=0&end_bwd_speech_search=3&end_fwd_speech_search=3&end_speech_stop_silence_before=0&end_speech_stop_silence_after=0&start_bwd_speech_search=1&start_fwd_speech_search=1&start_speech_stop_silence_before=0.5&start_speech_stop_silence_after=0.5&minimum_clip_separation=60&search_query=Dystopian+environment&add_keyword_tags=true&generate=false"

{
  "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"
      }
    }
  ]
}

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

Get generated preview clips details for gen id

Get previews generated clips details for asynchronous gen_id

Authorization

key<token>

In: query

Path Parameters

gen_idGen Id

Asynchronous gen task identifier

Response Body

curl -X GET "https://loading/results/jitpreviews/v1/gen/string"

curl -X GET "https://loading/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

Get information about the supported clip types (clip_type parameter) for a given version of the Previews product.

Authorization

key<token>

In: query

Query Parameters

version?Version

Previews version code

Response Body

curl -X GET "https://loading/results/jitpreviews/v2/info/clip_types?version=string"

curl -X GET "https://loading/results/jitpreviews/v2/info/clip_types?version=string"

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

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

Get Previews

Get previews for an item in the customer's catalog. This endpoint returns a list of timestamps for the clips that match the specified criteria. To get the actual video clips:

call this endpoint with trigger_generation=True to initiate the generation of previews clips. The return object will contain a unique gen_id for the generation task.
Using the gen_id, poll the /gen/{gen_id} endpoint to poll the status of the generation task. When the task is complete, the response will contain a list of paths to the generated video clips. The paths are relative to a pre-configured bucket.

Authorization

key<token>

In: query

Path Parameters

inventory_idInventory Id

Customer identifier for a movie or series item in the catalog

Query Parameters

version?Version

Previews version code

character?CharacterDeprecated

Default"None"

character_preference?CharacterPreference

Specifies how the character criteria should be applied.To apply character criteria, use any, any_of, all_of, None or avoid

Default"any"

character_list?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 or use any

Default"ANY"

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_dialog_boundary_search?End Bwd Dialog Boundary SearchDeprecated

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

Default0

Range0 <= value

end_fwd_dialog_boundary_search?End Fwd Dialog Boundary SearchDeprecated

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

Default0

Range0 <= value

start_bwd_dialog_boundary_search?Start Bwd Dialog Boundary SearchDeprecated

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

Default0

Range0 <= value

start_fwd_dialog_boundary_search?Start Fwd Dialog Boundary SearchDeprecated

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

Default0

Range0 <= value

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.

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.

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.

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.

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

Response Body

curl -X GET "https://loading/results/jitpreviews/v2/string?version=string&character=None&character_preference=any&character_list=string&number_of_top_candidates=5&clip_type=ANY&min_nudity=0&max_nudity=1&min_profanity=0&max_profanity=1&min_brightness=0&max_brightness=1&clip_length=30&skip_start=10&skip_end=10&start_bwd_snap_search=0&start_fwd_snap_search=0&end_bwd_snap_search=0&end_fwd_snap_search=0&end_bwd_dialog_boundary_search=0&end_fwd_dialog_boundary_search=0&start_bwd_dialog_boundary_search=0&start_fwd_dialog_boundary_search=0&end_bwd_scene_boundary_search=0&end_fwd_scene_boundary_search=0&start_bwd_scene_boundary_search=0&start_fwd_scene_boundary_search=0&end_bwd_speech_search=3&end_fwd_speech_search=3&end_speech_stop_silence_before=0&end_speech_stop_silence_after=0&start_bwd_speech_search=1&start_fwd_speech_search=1&start_speech_stop_silence_before=0.5&start_speech_stop_silence_after=0.5&minimum_clip_separation=60&search_query=Dystopian+environment&add_keyword_tags=true&generate=false&generate_vertical=false&trigger_generation=false&aspect_ratio=None"

curl -X GET "https://loading/results/jitpreviews/v2/string?version=string&character=None&character_preference=any&character_list=string&number_of_top_candidates=5&clip_type=ANY&min_nudity=0&max_nudity=1&min_profanity=0&max_profanity=1&min_brightness=0&max_brightness=1&clip_length=30&skip_start=10&skip_end=10&start_bwd_snap_search=0&start_fwd_snap_search=0&end_bwd_snap_search=0&end_fwd_snap_search=0&end_bwd_dialog_boundary_search=0&end_fwd_dialog_boundary_search=0&start_bwd_dialog_boundary_search=0&start_fwd_dialog_boundary_search=0&end_bwd_scene_boundary_search=0&end_fwd_scene_boundary_search=0&start_bwd_scene_boundary_search=0&start_fwd_scene_boundary_search=0&end_bwd_speech_search=3&end_fwd_speech_search=3&end_speech_stop_silence_before=0&end_speech_stop_silence_after=0&start_bwd_speech_search=1&start_fwd_speech_search=1&start_speech_stop_silence_before=0.5&start_speech_stop_silence_after=0.5&minimum_clip_separation=60&search_query=Dystopian+environment&add_keyword_tags=true&generate=false&generate_vertical=false&trigger_generation=false&aspect_ratio=None"

{
  "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,
        "valence": 0,
        "arousal": 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
          ]
        }
      }
    ]
  }
}

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

Get generated preview clips details for gen id

Get previews generated clips details for asynchronous gen_id

Authorization

key<token>

In: query

Path Parameters

gen_idGen Id

Asynchronous gen task identifier

Response Body

curl -X GET "https://loading/results/jitpreviews/v2/gen/string"

curl -X GET "https://loading/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 paginated list of the updated inventory_id items with the previews results statuses ordered by creation/update timestamp

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

Authorization

key<token>

In: query

Query Parameters

from_utcdatetime?From Utcdatetime

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

Formatdate-time

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

Formatdate-time

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

Previews version code

Response Body

curl -X GET "https://loading/results/jitpreviews/v2/?from_utcdatetime=2024-03-06T20%3A00%3A00&to_utcdatetime=2024-03-07T20%3A00%3A00&page_num=0&page_size=1000&version=string"

curl -X GET "https://loading/results/jitpreviews/v2/?from_utcdatetime=2024-03-06T20%3A00%3A00&to_utcdatetime=2024-03-07T20%3A00%3A00&page_num=0&page_size=1000&version=string"

{
  "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

200

422

200

403

404

422

200

422

200

422

200

422

200

403

404

422

On this page