Vyrill API Developer Portal
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 below
API Documentation
1. Share video URL API
2. Upload video API
3. Search API
4. Filter by video ID API
5. Filters + SKU API
6. Get list of brands
7. Get list of categories
1. Submit video URL API
The submit 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/v1/video/submit-video-url
Request Method:
POST
Headers:
{x-api-key: <Upload API Key>, Authorization:<Upload API Key>}
Request Body:
{
"videoUrl": "https://www.youtube.com/watch?v=9ATdi8dwjFH",
"platform": "Youtube", //allowed values: [“Youtube”, “Tiktok”, “Dropbox”]
"brandIds": ["63dca76f8c88272e24000004"], //optional
"productIds": ["63dcebcc8c8827b3b1000002"], //optional
"upc": ["63dcebcc8c8827b3b1000002"], //optional
"sku": [""], //optional
"categoryIds": [""], //optional
}
Response:
HTTP/1.1 200 OK
{
"videoId": "9000009DIe7DqZF65a",
}
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
The upload URL that is generated in this step is valid for 15 minutes.
Request URL:
https://api.vyrill.com/v1/video/create-upload-url/<file_extension>
Request Payload:
{file_extension: [mp4, mov, flv, 3gp, avi, wmv] }
Request Method:
GET
Headers:
{x-api-key: <Upload API Key>, Authorization:<Upload API Key>}
Request Body:
{
"brandIds": ["63c62e1f8c8827f594000002", "5ba90fec13d9c13508000001"], //optional
"productIds": ["63c62e5a8c8827ae0c000002"], //optional
"categoryIds": ["63b6b13800b2debddb000001", "6352c0ea13d9c1989e00001e"], //optional
"upc": "123456", //optional
"sku": "654321" //optional
}
Response:
HTTP/1.1 200 OK
{
"videoId": "63ddb4442df8e200084cbc45",
"uploadURL": "<URL>",
"actionId": "aac131f5-dc63-491a-b2fe-ff26f6219565-1675473345345",
"filename": "aac131f5-dc63-491a-b2fe-ff2r4t219565-1675475438.mp4"
}
Step 2. Upload the video using the generated pre-signed URL
Request URL:
<uploadURL from the response in step 1>
Request Method:
PUT
Headers:
{x-api-key: <Upload API Key>, Authorization:<Upload API Key>}
Request 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/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 any video analyzed by Vyrill. The video can be originally sourced from Youtube, TikTok or Dropbox.
Example request and response:
Request URL:
https://api.vyrill.com/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/v1/video?sku=9970240541&gender=female&ageRange=18-24ðnicity=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"
},{...}]
}
]
6. Get list of brands
Get a list of all brands associated with your account.
Request URL:
https://api.vyrill.com/v1/brands/
Request Method:
GET
Headers:
{x-api-key: <Fetch API Key>, Authorization:<Fetch API Key>}
Request Body:
N/A
Response:
HTTP/1.1 200 OK
[
{
"_id": "5ba90fec13d9c13508000001",
"name": "LANCOME",
"products": [
{
"_id": "5ba9138313d9c1439b000008",
"name": "Hydrogel Melting Mask"
},
{
"_id": "5c9a78dd13d9c14729000001",
"name": "ABSOLUE REVITALIZING & BRIGHTENING SOFT CREAM"
},
...
]
},
{
"_id": "62181bf113d9c187cb00004c",
"name": "Blacktravelbox",
"products": [
{
"_id": "62181d4813d9c187cb00004e",
"name": "Body Balm"
},
{
"_id": "62181d7413d9c187cb000051",
"name": "Conditioner Bar"
},
...
]
},
...
]
7. Get list of Categories
Get a list of all categories associated with your account.
Request URL:
https://api.vyrill.com/v1/categories/
Request Method:
GET
Headers:
{x-api-key: <Fetch API Key>, Authorization:<Fetch API Key>}
Request Body:
N/A
Response:
HTTP/1.1 200 OK
[
{
"_id": "50c0f8678d79bb124e000007",
"name": "Beauty"
},
{
"_id": "50c0f8678d79bb124e00000f",
"name": "Home appliances"
},
{
"_id": "50f841698f7f958bec000038",
"name": "Apparel and Clothing"
},
...
]
Release Notes
03/31/2023
- Added backend association between submit-video-url and create-upload-url endpoints
- Fixed API keys bug
Contact Us
Contact us at api-support@vyrill.com if you have any questions.