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
8. Get sentiment data for a video id
9. Get videos for a brand
10. Get brand information
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"],
"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 “computer vision”:
Request URL:
https://api.vyrill.com/v1/video?productId=646e20747e0802fbws4000008&search=computer vision&page=1&limit=20&sort=search_keyword_count&direction=desc
Request Method:
GET
Request Payload:
{
productId:646e20747e0802ff3b000008
search:computer vision
page:1
limit:20
sort:search_keyword_count
direction:desc}
Headers:
{x-api-key: <Fetch API Key>, Authorization:<Fetch API Key>}
Response:
[
{
"total": 116,
"perPage": "20",
"currentPage": "1",
"lastPage": 6,
"data": [
{
"_id": "6598e784cd6e9409f4713a5f",
"title": "Ask An Expert | How To Digitize A Physical Store According To Those Actually Doing It",
"video_desc": ""Digitizing the physical store" is one of those buzzword phrases pundits like to say but knowing how to do it is a different matter entirely. So Omni Talk is pleased to announce we assembled a top notch panel of real experts who are actually going about such work and can walk the walk",
"video_url": "https://www.youtube.com/watch?v=EqpnZoaMSWk",
"video_embedded_url": "https://www.youtube.com/embed/EqpnZoaMSWk",
"thumbnail_url": "https://i.ytimg.com/vi/EqpnZoaMSWk/hqdefault.jpg",
"duration": "PT52M38S",
"topics": [
"Comparison",
"Customer Experience",
"Implementation",
"News",
"Partnership",
"Promotions",
"Review",
"Scalability",
"Setup",
"Technology",
"Tutorial"
],
"likes": 0,
"view_count": 181,
"languages": [],
"aws_language": "en",
"search_keyword": "computer vision",
"published_date": "2023-06-27T20:27:05.000Z",
"sentence_timestamp": [
{
"sentence": "Welcome to another exciting and elucidating episode of the Omnitalk Ask And Experts Series.",
"start_time": "0:00:32"
},
...
],
"search_keyword_count": 23
}
{
"_id": "65a5f4f2686d5e13235ff581",
"title": "Spotlight Series: Standard Cognition CEO Jordan Fisher",
"video_desc": "Chris Walton and Anne Mezzenga interview Jordan Fisher, CEO of Standard Cognition, about the future of checkout-free retail.\n\nAI Computer vision-based checkout-free re
...
}
...
}
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"
},
...
]
8. Get sentiment data for a video id
Get the generative AI sentiment data associated with a particular video id
Request URL:
https://api.vyrill.com/v1/sentimentData/654df57383c3cc0008cbd003
Request Method:
GET
Headers:
{x-api-key: <Fetch API Key>, Authorization:<Fetch API Key>}
Request Body:
N/A
Response:
HTTP/1.1 200 OK
{
“summary”: {
“summary”: {
“bullets”: [
“Lenovo’s Legion 9i is a powerful and ambitious gaming laptop.“,
“The laptop features a forged carbon fiber finish for aesthetics.“,
“The mini LED screen has a high resolution, which may not be necessary for gaming.“,
“The Legion 9i is more expensive than the Legion 7 Pro, but the performance is largely the same.”
]
},
“section_summaries”: [
{
“summary”: {
“bullets”: [
“The mini LED screen has a high resolution, which may not be necessary for gaming.“,
“The Legion 9i is more expensive than the Legion 7 Pro, but the performance is largely the same.”
]
},
“start”: 3.1000000000000454,
“end”: 693.9748000000001
}
],
“usage”: {
“prompt_tokens”: 3222,
“completion_tokens”: 135,
“total_tokens”: 3357
}
},
“generativeSentiment”: {
“sentiment_analysis”: {
“comparison”: true,
“winner”: “Legion 7 Pro”,
“winner_reason”: “The Legion 7 Pro is considered the best gaming laptop for its screen and keyboard.“,
“summary_sentiments”: {
“positives”: [
“Lenovo Legion 9i is a powerful and ambitious laptop”,
“Triple fan setup and integrated water cooler are impressive innovations”,
“Keyboard is excellent”,
“Device comes with two power supplies for different needs”
],
“negatives”: [
“The water cooling system seems gimmicky and doesn’t provide significant benefits”,
“The trackpad is small”,
“The device is not the best for a top-tier gaming experience”
]
},
“products”: [
{
“name”: “Lenovo Legion 9i”,
“sentiment_score”: 70,
“summary”: “The Lenovo Legion 9i is a powerful and ambitious laptop with a unique forged carbon fiber finish. It features a triple fan setup and an integrated water cooler, although the effectiveness of the water cooling system is questionable. The keyboard is excellent, but the ergonomics are affected by the lowered keyboard. The high resolution screen may not be ideal for gaming. The device comes with two power supplies for different needs.“,
“positives”: [
“Powerful and ambitious laptop”,
“Unique forged carbon fiber finish”,
“Comes with two power supplies”
],
“negatives”: [
“More expensive than the Legion 7 Pro”,
“Not the best for a top-tier gaming experience”
],
“features”: [
{
“name”: “Forged Carbon Fiber Finish”,
“positives”: [
“Unique and aesthetically pleasing”
],
“negatives”: [
“Subjective appreciation”
]
},
{
“name”: “Triple Fan Setup”,
“positives”: [
“Impressive cooling performance”
],
“negatives”: [
“None mentioned”
]
},
{
“name”: “Integrated Water Cooler”,
“positives”: [
“Innovative design”
],
“negatives”: [
“Questionable effectiveness”
]
},
{
“name”: “Keyboard”,
“positives”: [
“Excellent typing experience”
],
“negatives”: [
“Ergonomics affected by lowered keyboard”
]
},
{
“name”: “Screen”,
“positives”: [
“High resolution and bright”
],
“negatives”: [
“Unnecessary for gaming”
]
}
]
},
{
“name”: “Legion 7 Pro”,
“sentiment_score”: 80,
“summary”: “The Legion 7 Pro is a highly regarded gaming laptop with a more traditional design. It offers a great gaming experience with its screen and keyboard. It is a more affordable option compared to the Legion 9i, but lacks the unique features of the 9i such as the forged carbon fiber finish and integrated water cooler.“,
“positives”: [
“Highly regarded gaming laptop”,
“Great gaming experience with screen and keyboard”,
“More affordable than the Legion 9i”
],
“negatives”: [
“Lacks unique features of the Legion 9i”,
],
“features”: []
}
]
},
“usage”: {
“prompt_tokens”: 3574,
“completion_tokens”: 924,
“total_tokens”: 4498
}
}
}
9. Get videos for a brand
Retrieve video metadata for a brand id
Request URL:
https://api.vyrill.com/v1/videos/64b401c17e08025a23000002
Request Method:
GET
Headers:
{x-api-key: <Fetch API Key>, Authorization:<Fetch API Key>}
Request Body:
N/A
Response:
HTTP/1.1 200 OK
{
“video_count”: 50,
“videos”: [
{
“_id”: “64b4c75be69aeb0008b78eab”,
“video_url”: “https://www.dropbox.com/s/jktavtr87g95pvo/sam%20altman.mp4?dl=0%22,
“platform”: “Dropbox”,
“upload_method”: “Vyrill_API”,
“thumbnail_url”: “https://denali-thumbnail-prod.s3.us-west-2.amazonaws.com/jktavtr8vo.jpg",
“video_embedded_url”: “”,
“duration”: “”
},
{
“_id”: “64cbf85a30f02c0008a5e09e”,
“duration”: “PT12M3S”,
“platform”: “Youtube”,
“thumbnail_url”: “https://i.ytimg.com/vi/GltxPY/hqefault.jpg",
“upload_method”: “Vyrill_API”,
“video_embedded_url”: “https://www.youtube.com/embed/GltxhPY",
“video_url”: “https://www.youtube.com/watch?v=GltxY"
},
{
“_id”: “64d2b3860f90190008936b5f”,
“duration”: “PT21M53S”,
“platform”: “Youtube”,
“thumbnail_url”: “https://i.ytimg.com/vi/H0RQ-Q/hqdefault.jpg",
“upload_method”: “Vyrill_API”,
“video_embedded_url”: “https://www.youtube.com/embed/H0RseQ-Q",
“video_url”: “https://youtu.be/H0Rse-Q"
},
{
“_id”: “64d2fbd81bb83e00098a87b4",
“video_url”: “https://denali-video-upload-prod.s3.us-west-2.amazonaws.com/3da5b6f9-9c93-40c9-a33c-1691548632.mp4",
“platform”: “Vyrill_AWS_S3",
“upload_method”: “Vyrill_API”
},
...
]
}
10. Get brand information
Get brand info associated with this API key
Request URL:
https://api.vyrill.com/v1/brand-info
Request Method:
GET
Headers:
{x-api-key: <Fetch API Key>, Authorization:<Fetch API Key>}
Request Body:
N/A
Response:
HTTP/1.1 200 OK
{
"email": "test_brand@vyrill.com",
"brands": [
{
"_id": "64b401c17e08025a2300ges2",
"name": "test-brand"
}
]
}
Release Notes
11/28/2023
- Added API endpoint for /v1/brand-info
Contact Us
Contact us at api-support@vyrill.com if you have any questions.