Vionlabs Thumbnails API
Vionlabs API for on-request assembling of thumbnails results.
Get Thumbnails
Get thumbnails for an item in the customer catalog (movie or series) This endpoint is deprecated. Please use the v2 endpoint instead.
In: query
Path Parameters
Customer identifier for a movie or series item in the catalog
Query Parameters
Thumbnails version code
Specifies which character(s) will appear in results.Characters are identified by integer rank (0, 1, 2, ...), i.e. 0 is the main character, 1 is the second main character, etc.Use CharacterSelector.ANY to include any character. Use CharacterSelector.NONE to allow thumbnails without characters (e.g. landscapes).To get a specific character, use 1 or 2 etc. Asking for a specific character doesn't guarantee exclusivity, other characters might be present. To get multiple characters, use comma separated values, e.g. 1,2
"any"Determines the size of the specified character in the frame. If returning more than one specific character, we recommend leaving this setting blank.
"any"Designates where the specified character should be in the frame.If returning more than one specific character, we recommend leaving this setting blank.
"any"Max allowed degree to which motion is detected in a frame. The lower the score, the less likely it is that motion will obscure details of the frame. We recommend taking this parameter as information, and fine-tuning image blur and facial clarity separately via sobel_score, max_brisque, and img_laplacian instead
1000 <= valueUse min_brightness instead.
00 <= value <= 1The minimum allowed degree of the frame's brightness. The higher the score, the brighter the frames will be. Increase this value to avoid dark frames.
00 <= value <= 1The maximum allowed degree of the frame's brightness. The lower the score, the darker the frames will be. Decrease this value to avoid too bright frames.
10 <= value <= 1Use min_eye_openness instead.
0.20 <= value <= 1Minimum acceptable extent to which the specified character(s) eyes are open. The higher the score, the wider the eyes of each character will be. E.g. a value of 0.0 permits characters with completely closed eyes. Setting this value to .20 generally avoids eyes that are closed or half-open and returns eyes in a neutral position.
0.20 <= value <= 1Maximum acceptable extent to which the specified character(s) eyes are open. The lower the score, the more closed the eyes of each character will be. E.g. setting this value to values lower than around 0.2 will restrict characters to having closed eyes.
10 <= value <= 1Use max_mouth_openness instead.
10 <= value <= 100Minimum acceptable extent to which the specified character(s) mouth(s) are open. The higher the score, the more open the mouths of each character will be. E.g. a values close to 1.0 will restrict characters to having completely open mouths.
00 <= value <= 1Maximum acceptable extent to which the specified character(s) mouth(s) are open. The smaller the score, the less open the mouths of each character will be. E.g. a value of 0.0 restricts characters to having completely closed mouths.
10 <= value <= 1The minimum number of seconds between candidate frames returned. The higher the value, the greater the diversity of frames returned will be. A higher value risks eliminating otherwise good candidates on the basis of them being too close to other good candidates. We aim to minimize this risk by setting the default value. Correlates with all other parameters. The stricter the criteria applied, the less candidates yielded overall, and thus the less candidates available to space out according to the separation value.
300 <= valueThe maximum number of top candidate frames to return.The higher the number, the more frames will be returned after applying all criteria and sorting them with respect to their composite scores. Please note that stricter criteria leads to fewer acceptable candidates overall, and may in turn reduce the number of top candidates to choose from.
150 <= valueUse min_backdropness_score instead.
00 <= value <= 1Minimum acceptable degree to which a frame is aesthetically pleasing. The higher the score, the more aesthetically pleasing a frame is overall. This value is particularly important for frames that are not focused on the character, as the aesthetics of the background are not visible for close-up shots, and thus tend to score much lower. For this reason, when returning frames containing characters (i.e. not just landscapes) we suggest controlling this value via the backdrop_importance parameter instead.
00 <= value <= 1Maximum acceptable degree to which a frame is aesthetically pleasing. The lower the score, the less aesthetically pleasing a frame is overall. We recommend keeping this value at the maximum value, as it is generally not desirable to return frames that are not aesthetically pleasing for thumbnails.
10 <= value <= 1Use min_relevance_score instead.
00 <= value <= 1Minimum allowed relevance score. The higher the score, the more representative a frame's content is of the asset's overall storyline.
00 <= value <= 1Maximum allowed relevance score. The lower the score, the less representative a frame's content is of the asset's overall storyline.
10 <= value <= 1Use min_composite_score instead.
00 <= value <= 1Minimum composite score allowed. The higher the score, the higher the overall expected performance for both min_backdropness_score (aesthetics) and min_relevance_score.
00 <= value <= 1Maximum composite score allowed. The lower the score, the lower the overall expected performance for both min_backdropness_score (aesthetics) and min_relevance_score.
10 <= value <= 1Use max_brisque instead.
400 <= value <= 100The minimum allowed degree to which character faces are blurred overall. The higher the score, the more blurry the faces will be.
00 <= value <= 1The degree to which character faces are in focus overall (i.e. not blurry). The lower the score, the clearer the faces will be. Most frames with a brisque score under 0.4 are typically acceptable
0.40 <= value <= 1Minimum acceptable degree to which character faces are defined (i.e. with sharp details). The higher the score, the stronger the contours and details in characters' faces will be. For assets of normal resolution and quality, a minimum score of 350 typically yields assets with acceptable levels of sharpness.
00 <= valueMin laplacian variance allowed. The higher the score, the more the frame will be in focus overall. For assets of normal resolution and quality, a minimum score of 100 typically eliminates most blurry frames from results.Consider this value together with sobel_score. Frames with an artistic background blur and a foreground character in focus may have a lower laplacian score and a higher sobel score (a blurry background and a strongly defined face).
00 <= valueWeight given to aesthetic in composite scoring. The higher the score, the greater the proportion of the composite score that will be represented by the aesthetics of the frame's backdrop. We generally keep this value at .70 to return frames with both aesthetically pleasing backdrops as well as frames with closeups containing less backdrop information.
0.70 <= value <= 1Weight given to relevance in composite scoring. The higher the score, the greater the proportion of the composite score will rely on the frame's representativeness of the asset's overall storyline. We generally keep this value at .30 to maximize representativeness while maintaining diversity.
0.30 <= value <= 1Use max_nudity instead.
10 <= value <= 1Min required nudity probability. Increase this value to get content with more nudity. Introduced in version 7.
00 <= value <= 1Max allowed nudity probability. Introduced in version 7.
10 <= value <= 1A percentage of the asset length in the beginning of the video from which no thumbnails can be selected.
0A percentage of the asset length in the end of the video from which no thumbnails can be selected.
0If true, exclude thumbnails with subtitles and overlay graphics. Introduced in version 11.
falseThreshold for character classification. Controls trade-off between precision and recall where a higher value gives higher precision at the cost of recall. Only applicable for anime content
0.70 <= value <= 1Initiate asynchronous process of thumbnails images extraction
falseResponse Body
curl -X GET "https://loading/results/jitthumbnails/v1/string?version=string&character=any&closeup=any&position=any&stillness=100&brightness=0&min_brightness=0&max_brightness=1&eye_status=0.2&min_eye_openness=0.2&max_eye_openness=1&mouth_status=1&min_mouth_openness=0&max_mouth_openness=1&separation=30&number_of_top_candidates=15&score=0&min_backdropness_score=0&max_backdropness_score=1&relevance=0&min_relevance_score=0&max_relevance_score=1&composite_score=0&min_composite_score=0&max_composite_score=1&brisque=40&min_brisque=0&max_brisque=0.4&sobel_score=0&img_laplacian=0&backdrop_importance=0.7&relevance_importance=0.3&nudity_threshold=1&min_nudity=0&max_nudity=1&skip_start=0&skip_end=0&exclude_subtitles=false&ct_threshold=0.7&generate=false"{
"inventory_id": "string",
"type": "movie",
"vionlabs_id": "string",
"version_id": "string",
"gen_id": "string",
"jitthumbnail": [
{
"frame_index": 0,
"pts": 0,
"score": 0,
"relevance": 0,
"timestamp": 0,
"characters": [],
"stillness": 0,
"brightness": 0,
"color": [
null
],
"composite_score": 0,
"img_laplacian": 0,
"nudity": 0,
"subtitles": 0,
"gen": {
"large_image_path": "string",
"small_image_path": "string"
}
}
]
}{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}Get Portraits
Get character portraits for an asset. This endpoint is deprecated. Please use the v2 endpoint instead.
In: query
Path Parameters
Customer identifier for a movie or series item in the catalog
Query Parameters
If True, artificially increase the brightness of the portraits if deemed dark.
falseOnly return portraits for top k characters
-1JitThumbnail version code
Response Body
curl -X GET "https://loading/results/jitthumbnails/v1/string/portraits?adjust_brightness=false&top_k=-1&version=string"{
"portraits": {}
}{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}Get generated thumbnails images details for gen id
Get jit thumbnails generated images details for asynchronous gen_id
In: query
Path Parameters
Asynchronous gen task identifier
Response Body
curl -X GET "https://loading/results/jitthumbnails/v1/gen/string"{
"inventory_id": "string",
"type": "movie",
"vionlabs_id": "string",
"version_id": "string",
"gen_id": "string",
"context": {},
"jitthumbnail": [
{
"frame_index": 0,
"gen": {
"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"
}
]
}Extract Frame
Extracts a single PNG frame from a video at a specified timestamp.
In: query
Video URL to extract the frame from
Timestamp in seconds to extract at
Response Body
curl -X POST "https://loading/results/jitthumbnails/v2/extract-frame" \ -H "Content-Type: application/json" \ -d '{ "video_url": "string", "timestamp": 0 }'"string"{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}Get Thumbnails
Get thumbnails for an item in the customer catalog (movie or series)
In: query
Path Parameters
Customer identifier for a movie or series item in the catalog
Query Parameters
Thumbnails version code
Specifies the preference for the specified character(s) in the frame. Use any to include at least one character. Use None to allow thumbnails without characters.Use avoid to avoid characters (e.g. landscapes).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.
"any"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.
The maximum number of top candidate frames to return.The higher the number, the more frames will be returned after applying all criteria and sorting them with respect to their composite scores. Please note that stricter criteria leads to fewer acceptable candidates overall, and may in turn reduce the number of top candidates to choose from.
150 <= valueDetermines the size of the specified character in the frame. If returning more than one specific character, we recommend leaving this setting blank.
"any"Designates where the specified character should be in the frame.If returning more than one specific character, we recommend leaving this setting blank.
"any"Max allowed degree to which motion is detected in a frame. The lower the score, the less likely it is that motion will obscure details of the frame. We recommend taking this parameter as information, and fine-tuning image blur and facial clarity separately via sobel_score, max_brisque, and img_laplacian instead
1000 <= valueThe minimum allowed degree of the frame's brightness. The higher the score, the brighter the frames will be. Increase this value to avoid dark frames.
00 <= value <= 1The maximum allowed degree of the frame's brightness. The lower the score, the darker the frames will be. Decrease this value to avoid too bright frames.
10 <= value <= 1Minimum acceptable extent to which the specified character(s) eyes are open. The higher the score, the wider the eyes of each character will be. E.g. a value of 0.0 permits characters with completely closed eyes. Setting this value to .20 generally avoids eyes that are closed or half-open and returns eyes in a neutral position.
0.20 <= value <= 1Maximum acceptable extent to which the specified character(s) eyes are open. The lower the score, the more closed the eyes of each character will be. E.g. setting this value to values lower than around 0.2 will restrict characters to having closed eyes.
10 <= value <= 1Minimum acceptable extent to which the specified character(s) mouth(s) are open. The higher the score, the more open the mouths of each character will be. E.g. a values close to 1.0 will restrict characters to having completely open mouths.
00 <= value <= 1Maximum acceptable extent to which the specified character(s) mouth(s) are open. The smaller the score, the less open the mouths of each character will be. E.g. a value of 0.0 restricts characters to having completely closed mouths.
10 <= value <= 1The minimum number of seconds between candidate frames returned. The higher the value, the greater the diversity of frames returned will be. A higher value risks eliminating otherwise good candidates on the basis of them being too close to other good candidates. We aim to minimize this risk by setting the default value. Correlates with all other parameters. The stricter the criteria applied, the less candidates yielded overall, and thus the less candidates available to space out according to the separation value.
300 <= valueMinimum acceptable degree to which a frame is aesthetically pleasing. The higher the score, the more aesthetically pleasing a frame is overall. This value is particularly important for frames that are not focused on the character, as the aesthetics of the background are not visible for close-up shots, and thus tend to score much lower. For this reason, when returning frames containing characters (i.e. not just landscapes) we suggest controlling this value via the backdrop_importance parameter instead.
00 <= value <= 1Maximum acceptable degree to which a frame is aesthetically pleasing. The lower the score, the less aesthetically pleasing a frame is overall. We recommend keeping this value at the maximum value, as it is generally not desirable to return frames that are not aesthetically pleasing for thumbnails.
10 <= value <= 1Minimum allowed relevance score. The higher the score, the more representative a frame's content is of the asset's overall storyline.
00 <= value <= 1Maximum allowed relevance score. The lower the score, the less representative a frame's content is of the asset's overall storyline.
10 <= value <= 1Minimum composite score allowed. The higher the score, the higher the overall expected performance for both min_backdropness_score (aesthetics) and min_relevance_score.
00 <= value <= 1Maximum composite score allowed. The lower the score, the lower the overall expected performance for both min_backdropness_score (aesthetics) and min_relevance_score.
10 <= value <= 1The minimum allowed degree to which character faces are blurred overall. The higher the score, the more blurry the faces will be.
00 <= value <= 1The degree to which character faces are in focus overall (i.e. not blurry). The lower the score, the clearer the faces will be. Most frames with a brisque score under 0.4 are typically acceptable
0.250 <= value <= 1Minimum acceptable degree to which character faces are defined (i.e. with sharp details). The higher the score, the stronger the contours and details in characters' faces will be. For assets of normal resolution and quality, a minimum score of 350 typically yields assets with acceptable levels of sharpness.
00 <= valueMin laplacian variance allowed. The higher the score, the more the frame will be in focus overall. For assets of normal resolution and quality, a minimum score of 100 typically eliminates most blurry frames from results.Consider this value together with sobel_score. Frames with an artistic background blur and a foreground character in focus may have a lower laplacian score and a higher sobel score (a blurry background and a strongly defined face).
00 <= valueWeight given to aesthetic in composite scoring. The higher the score, the greater the proportion of the composite score that will be represented by the aesthetics of the frame's backdrop. We generally keep this value at .70 to return frames with both aesthetically pleasing backdrops as well as frames with closeups containing less backdrop information.
0.70 <= value <= 1Weight given to relevance in composite scoring. The higher the score, the greater the proportion of the composite score will rely on the frame's representativeness of the asset's overall storyline. We generally keep this value at .30 to maximize representativeness while maintaining diversity.
0.30 <= value <= 1Min required nudity probability. Increase this value to get content with more nudity. Introduced in version 7.
00 <= value <= 1Max allowed nudity probability. Introduced in version 7.
10 <= value <= 1A percentage of the asset length in the beginning of the video from which no thumbnails can be selected.
0A percentage of the asset length in the end of the video from which no thumbnails can be selected.
0If true, exclude thumbnails with subtitles and overlay graphics. Introduced in version 11.
falseThreshold for character classification. Controls trade-off between precision and recall where a higher value gives higher precision at the cost of recall. Only applicable for anime content
0.70 <= value <= 1Search query to filter thumbnails
Initiate asynchronous process of thumbnails images extraction. Only one of generate or generate_vertical can be True.DEPRECATED. Use trigger_generation instead.
falseInitiate asynchronous process of vertical thumbnails images 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.
falseTrigger the generation of thumbnails. Introduced in version 15.
falseInclude logo information in the response, only supported for versions with -logo suffix and above 17.
falseAspect ratio of the thumbnails. When set, an addition cropping information is returned in the response (vertical_conversion field). Only supported with versions with -vertical suffix.
"None"Response Body
curl -X GET "https://loading/results/jitthumbnails/v2/string?version=string&character_preference=any&character_list=string&number_of_top_candidates=15&closeup=any&position=any&stillness=100&min_brightness=0&max_brightness=1&min_eye_openness=0.2&max_eye_openness=1&min_mouth_openness=0&max_mouth_openness=1&separation=30&min_backdropness_score=0&max_backdropness_score=1&min_relevance_score=0&max_relevance_score=1&min_composite_score=0&max_composite_score=1&min_brisque=0&max_brisque=0.25&sobel_score=0&img_laplacian=0&backdrop_importance=0.7&relevance_importance=0.3&min_nudity=0&max_nudity=1&skip_start=0&skip_end=0&exclude_subtitles=false&ct_threshold=0.7&search_query=string&generate=false&generate_vertical=false&trigger_generation=false&add_logo=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",
"jitthumbnail": [
{
"frame_index": 0,
"pts": 0,
"frame_size": [
0,
0
],
"black_bars": [
0,
0
],
"score": 0,
"relevance": 0,
"timestamp": 0,
"characters": [],
"stillness": 0,
"brightness": 0,
"color": [
null
],
"composite_score": 0,
"nudity": 0,
"subtitles": 0,
"logo_position": [
{
"size": 0,
"coordinates": [
0,
0
],
"logo_name": "string",
"score": 0,
"logo": "string"
}
],
"vertical_conversion": {
"coordinates": 0,
"blackbars": [
0,
0
],
"aspect_ratio": "None"
},
"gen": {
"large_image_path": "string",
"small_image_path": "string"
}
}
]
}
}{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}Get Portraits
Get character portraits for an asset.
In: query
Path Parameters
Customer identifier for a movie or series item in the catalog
Query Parameters
If True, artificially increase the brightness of the portraits if deemed dark.
falseOnly return portraits for top k characters
-1JitThumbnail version code
Response Body
curl -X GET "https://loading/results/jitthumbnails/v2/string/portraits?adjust_brightness=false&top_k=-1&version=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",
"portraits": {}
}
}{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}Get generated thumbnails images details for gen id
Get jit thumbnails generated images details for asynchronous gen_id
In: query
Path Parameters
Asynchronous gen task identifier
Response Body
curl -X GET "https://loading/results/jitthumbnails/v2/gen/string"{
"inventory_id": "string",
"type": "movie",
"vionlabs_id": "string",
"version_id": "string",
"gen_id": "string",
"context": {},
"jitthumbnail": [
{
"frame_index": 0,
"gen": {
"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"
}
]
}