Introduction

Welcome to the Vyrill developer site. We’re excited you’re here to leverage the power of Vyrill’s video intelligence and 'In-video' search capabilities.

Our innovative API allows you to manage, rate and leverage your video data and access the metrics we provide without relying on our web application.

The Vyrill Video API allows developers to make video content searchable and useful. Brands can accelerate shopper purchase decisions by enhancing the customer experience with video and helping shoppers find answers inside video content.

To learn more about video intelligence and how you can use Vyrill to take your business to the next level, please contact us at sales@vyrill.com.

Our AI-driven ‘In-video’ search scans the audio, images and text within each video for:

Positive & Negative Sentences 
Trending Topics & Keywords
Trending Videos & Creators
Ethnicity, Age, Gender
Experts, Fans, Press or Sponsored
Profanity, Minors and Nudity
Indoor or Outdoor Scenes
Speech, Music, Noise, Silence
Language

Get Started

Follow these steps to sign up, get your API key, make your first API call, and interpret the results.

Step 1: Get in Touch with Our Team

Share your contact information here, and our team will reach out to discuss your needs.

Step 2: Get Your API Key and Vyrill Account

Our team will be in touch with you shortly at the email submitted in the above form to provide you with the API key. Then we will set up your Vyrill dashboard account so you can build apps, track your API calls, and access your video analysis results.

Step 3: Make an API Call

Find the list of API calls and documentation here.

API Documentation

1. Share video URL API
2. Upload video API
3. Search API
4. Filter by video ID API
5. Filters + SKU API

1.  Share video URL API

The share video URL API allows you to submit the URL of a YouTube, TikTok, or Dropbox video to get it analyzed. The video analysis will be available after 24 hours.

Example request and response:

Request URL:
https://api.vyrill.com/prod/v1/video/submit_video?url=https://youtu.be/rHYQ0NayXzE
Request Method:
POST
Headers:
{x-api-key: <Upload API Key>, Authorization:<Upload API Key>}
Request Payload:
{url: video_url}
Response:
{   "video": video_object,    "shared_platform_details":  {platform_details}}

2.  Upload video API

The upload video API allows you to upload a video for analysis. Uploading a video is a two-step process:

Step 1. Generate a pre-signed video upload URL
Request URL:
https://api.vyrill.com/prod/v1/video/upload/<file_extension>
Request Method:
GET
Request Payload:
{file_extension: [mp4, mov, flv, 3gp, avi, wmv] }
Headers:
{x-api-key: <Upload API Key>, Authorization:<Upload API Key>}
Response:
HTTP/1.1 200 OK 
{   "uploadURL": "https://xxx.s3.us-west-2.amazonaws.com/166910873.mov?  AWSAccessKeyId=ASJ",   "lastname": "166910873.mov" }

Step 2. Upload the video using the generated pre-signed URL
Request URL:
https://xxx.s3.us-west-2.amazonaws.com/166910873.mov?AWSAccessKeyId=ASJ
Request Method:
PUT
Request Payload:
{file_extension: [mp4, mov, flv, 3gp, avi, wmv] }
Headers:
{x-api-key: <Upload API Key>, Authorization:<Upload API Key>}
Body:
video file in binary format
Response:
HTTP/1.1 200 OK

3.  Search API

The Search API allows you to get video analysis search results based on a search term.

Example request and response using the search term “makeup”:

Request URL:
https://api.vyrill.com/prod/v1/video/?productId=9970240541&search=makeup
Request Method:
GET
Request Payload:
{productId: 9970240541, search: “makeup” }
Headers:
{x-api-key: <API Key>, Authorization:<API Key>}
Response:

[

   {

       "_id": "61af8eb913d9c1c443000070",

       "title": "over 50 makeup mature skin lancome teint idole ultra wear foundation test",

       "video_desc": "over 50 makeup lancome foundation test get ready with almay multi-benefit mascara",

       "video_url": "https://www.youtube.com/watch?v=cyg_wg9MMck",

       "thumbnail_url": "https://i.ytimg.com/vi/cyg_wg9MMck/hqdefault.jpg",

       "duration": "PT40M13S",

       "product_names": [

           "Teint Idole Ultra Wear 24 hour Foundation"

       ],

       "topics": [

           "eyes",

           "makeups",

           "lips",

           "tutorial"

       ],

       "upload_method": "Manual Products AVA",

       "languages": [

           "English"

       ],

       "scene_labels": [

           "Beauty Salon",

           "Room",

           "Store",

           "Bedroom",

           "Hospital"

       ],

       "scene_thumbnails": [

           "https://s3-us-west-2.amazonaws.com/scenethumbnails/cyg_wg9MMck/test_0.jpg",

       ],

       "transcription_text": "",

       "keywords": [

           {

               "keyword": "aqua net",

               "score": 30.14

           },

           },

           {

               "keyword": "makeup wipe",

               "score": 27.42

           },

       ],

       "positive_sent_MLB": 37,

       "negative_sent_MLB": 8,

       "aws_language": "en-US",

       "sentiment_ml_at_b_file_content": [

            {

               "Sentence": "I am just playing around today, getting ready for the day.",

               "Class": "1",

               "Prob_Neut": "0.3023612",

               "Prob_Pos": "0.56554115",

               "Prob_Neg": "0.1320976",

               "Start_time": "0:00:22"

           },

           {

               "Sentence": "I am testing my can make mermaid gel.",

               "Class": "1",

               "Prob_Neut": "0.2997946",

               "Prob_Pos": "0.59246093",

               "Prob_Neg": "0.107744515",

               "Start_time": "0:00:26"

           },

           {

               "Sentence": "It's a sunscreen.",

               "Class": "1",

               "Prob_Neut": "0.32045424",

               "Prob_Pos": "0.52284926",

               "Prob_Neg": "0.15669654",

               "Start_time": "0:00:36"

           },

            {

               "Sentence": "So it's not dry, and I just want to see how it does just really on bare skin.",

               "Class": "0",

               "Prob_Neut": "0.43644",

               "Prob_Pos": "0.16613121",

               "Prob_Neg": "0.39742875",

               "Start_time": "0:03:39"

           },

     

       ],

       "video_diversity_info": {

           "_id": "61bc97ea3916d19b2e000011",

           "number_of_white_people": 2,  

           "number_of_40_to_50_people": 1,

           "number_of_50_to_60_people": 1,

           "number_of_60_plus_people": 0,

           "age_diversity": 55.56,

           "number_of_females": 2,

           "number_of_people": 2

       },

       "brand_safety_measure": "Safe",

       "positive_sentences": [

           {

               "positive_sentence": "Perfect sunscreen foundation combo.",

               "pb": 0.9686254,

               "time_stamp": "0:06:39"

           },

           {

               "positive_sentence": "The urban decay eyeshadow, potion primer, original Love it.",

               "pb": 0.94920826,

               "time_stamp": "0:22:45"

           },

              {

              {

               "positive_sentence": "This shimmer, and it really just picks up my texture.",

               "pb": 0.7207098,

               "time_stamp": "0:27:12"

           }

       ],

       "negative_sentences": [

           {

               "negative_sentence": "I don't like this at all.",

               "pb": 0.9349991,

               "time_stamp": "0:10:47"

           },

           {

               "negative_sentence": "I was like, Oh, not good, Not good.",

               "pb": 0.8819888,

               "time_stamp": "0:24:17"

           },

           {

               "negative_sentence": "It never worked for me.",

               "pb": 0.8609516,

               "time_stamp": "0:36:22"

           },

           {

               "negative_sentence": "It makes the whole thing looks worse.",

               "pb": 0.85145986,

               "time_stamp": "0:23:16"

           },

          ],

       "demographics_data": [

           {

               "number_of_people": 2,

               "demographics_labels": [

                   {

                       "person_type": "Person",

                       "age_range": "50-60",

                       "gender": "female",

                       "ethnicity": "white",

                       "presence_percentage": 77.2,

                       "first_occurrence": "0:00:01"

                   },

                   {

                       "person_type": "Person",

                       "age_range": "40-50",

                       "gender": "female",

                       "ethnicity": "white",

                       "presence_percentage": 0.4,

                       "first_occurrence": "0:04:35"

                   }

               ]

           }

       ]

   }

]

4.  Filter by video ID API

The filter by video ID API allows you to fetch a video analysis for a video hosted on Dropbox.

Example request and response:

Request URL:
https://api.vyrill.com/dev/v1/video/63206ad513d9c14c7b000001
Request Method:
GET
Headers:
{x-api-key: <API Key>, Authorization:<API Key>}
Request Payload:
{videoId: 63206ad513d9c14c7b000001}
Response:

[

    {

        "_id": "5ca45f022d737f8759000b60",

        "title": "Beauty video influencer1 ",

        "video_desc": "Dropbox video",

        "video_url": "https://www.dropbox.com/s/6zm0d/Dropbox%206%20-%201%20.webm?dl=0",

        "product_names": ["Banana cream soda",””],

        "topics": ["review"],

        "upload_method": "API",

        "languages": [“English”],

        "scene_labels": [“room”,”store”],

        "scene_thumbnails": [“https://s3-us-west-2.amazonaws.com/thumbnails/scenes/633/room.jpg"”],

        "transcription_text": "I've had a coffee with a lollipop strawberry, vanilla, strawberry, vanilla…",

        "keywords": [

{

                "keyword": "banana cream",

                "score": 7.83

            },

{

                "keyword": "lollipop strawberry",

                "score": 3.5

            },

…],

        "positive_sent_MLB": 2,

        "negative_sent_MLB": 1,

        "sentiment_ml_at_b_file_content": [{

                "Class": "1",

                "Prob_Neg": "0.04615896",

                "Prob_Neut": "0.3309429",

                "Prob_Pos": "0.6228981",

                "Sentence": "It's definitely banana cream.",

                "Start_time": "0:00:06"

            },{...}],

        "video_diversity_info": {

"_id": "632481b93916d1d8ab00007f",

            "number_of_white_people": 0,

            "number_of_black_people": 1,

"number_of_people": 1},

        "brand_safety_measure": "Safe",

        "positive_sentences": [

{

                "positive_sentence": "Jones is one of my favorite coffee shops.",

                "pb": 0.8912406,

                "time_stamp": "0:00:51"

            }, {...}],

        "negative_sentences": [

{

                "negative_sentence": "It simply cannot be.",

                "pb": 0.81926906,

                "time_stamp": "0:00:14"

            }],

        "demographics_data": [{

                "number_of_people": 1,

                "demographics_labels": [

                    {

                        "person_type": "Person",

                        "age_range": "18-24",

                        "gender": "female",

                        "ethnicity": "black",

                        "presence_percentage": 93.3,

                        "first_occurrence": "0:00:01"

                    }

                ]

            }

       ]

    }

]

5.  Filters + SKU API

The Filters + SKU API allows you to fetch a video analysis for a certain SKU and a filter criteria.

Example request and response:

Request URL:
https://api.vyrill.com/dev/v1/video?sku=9970240541&gender=female&ageRange=18-24&ethnicity=hispanic
Request Method:
GET
Headers:
{x-api-key: <API Key>, Authorization:<API Key>}
Request Payload:
{sku: 9970240541, gender: female, ageRange: 18-24, ethnicity: hispanic}
Response:

[

    {

        "_id": "631ad39813d9c1836000003a",

        "title": "<3 on TikTok",

        "video_desc": "Part 2 beauty tutorial #foryou #xyzbca #trending",

        "video_url": "https://www.tiktok.com/@luvxryu1/video/7125959557569957121",

        "thumbnail_url": "https://p16-sign-sg.tiktokcdn.com/obj/tos-alisg-p-0037",

        "duration": "..",

        "product_names": [“Estee Lauder pure color blush”,”Teint Idole Ultra Wear 24 hour Foundation”],

        "topics": [],

        "upload_method": "API",

        "languages": ["English"],

        "scene_labels": ["Store", "Coffee Shop"],

        "scene_thumbnails": ["https://s3-us-west-2.amazonaws.com/scenethumbnails/7125/test_0.jpg”],

        "transcription_text": "um This is the color I want. It's gonna match the mani and pedi...",

        "keywords": [{ "keyword": "popular color", "score": 8},{...}],

        "positive_sent_MLB": 5,

        "negative_sent_MLB": 2,

        "sentiment_ml_at_b_file_content": [{

"Sentence": "um This is the color I want.",

"Class": "1",

"Prob_Neut": "0.28134638",

"Prob_Pos": "0.6192321",

"Prob_Neg": "0.099421464",

"Start_time": "0:00:00"

},{...}],

        "video_diversity_info": {

"_id": "631f3d2e3916d16a7a000063", 

"number_of_white_people": 2},

        "brand_safety_measure": "Safe",

        "positive_sentences": [

{

"positive_sentence": 

"Have fun ourselves.",

"pb": 0.7436936, 

"time_stamp":"0:01:06"},

{...}

],

        "negative_sentences": [

"negative_sentence": "I know, I'm so sorry.", 

"pb": 0.8408585, 

"time_stamp": "0:00:07"},

{...}],

        "demographics_data": [

"number_of_people": 2,

"demographics_labels": [

{

"person_type": "Person",

"age_range": "25-30",

"gender": "female",

"ethnicity": "hispanic",

"presence_percentage": 24.5,

"first_occurrence": "0:00:03"

},

{

"person_type": "Person",

"age_range": "25-30",

"gender": "female",

"ethnicity": "white",

"presence_percentage": 17.9,

"first_occurrence": "0:00:14"

},{...}]

    }

]

Release Notes

12/29/2022

12/29/22API version 2.0.0 has been released with the following endpoints:

Contact Us

Contact us at api-support@vyrill.com if you have any questions.