s
social media video downloader
# SMVD API Documentation
SMVD (Social Media Video Downloader) is a comprehensive API for extracting video details, metadata, transcripts, and download links from YouTube, Instagram, and Facebook. This API provides advanced features including proxy support, video rendering, caching, and subscription-based access controls.
## Table of Contents
- [Authentication](#authentication)
- [API Endpoints](#api-endpoints)
- [Health Check](#health-check)
- [YouTube Video Details](#youtube-video-details)
- [YouTube Video Comments](#youtube-video-comments)
- [YouTube Post Details](#youtube-post-details)
- [YouTube Post Comments](#youtube-post-comments)
- [YouTube Channel Details](#youtube-channel-details)
- [YouTube Channel ID from Handle](#youtube-channel-id-from-handle)
- [YouTube Channel Videos](#youtube-channel-videos)
- [YouTube Channel Playlists](#youtube-channel-playlists)
- [YouTube Channel Posts](#youtube-channel-posts)
- [YouTube Hashtag](#youtube-hashtag)
- [YouTube Playlists](#youtube-playlists)
- [YouTube Search](#youtube-search)
- [Instagram Media Post](#instagram-media-post)
- [Instagram User ID from Username](#instagram-user-id-from-username)
- [Instagram User Profile](#instagram-user-profile)
- [Facebook Post Details](#facebook-post-details)
- [Facebook Profile Details](#facebook-profile-details)
- [Facebook Profile ID](#facebook-profile-id)
- [Facebook Profile About](#facebook-profile-about)
- [Facebook Profile Reels](#facebook-profile-reels)
- [Facebook Profile Photos](#facebook-profile-photos)
- [TikTok User Details](#tiktok-user-details)
- [TikTok Post Details](#tiktok-post-details)
- [Renderable Formats](#renderable-formats)
- [RenderConfig Usage Guide](#renderconfig-usage-guide)
- [Request Parameters](#request-parameters)
- [Response Format](#response-format)
- [Error Handling](#error-handling)
- [Rate Limiting & Subscription Tiers](#rate-limiting--subscription-tiers)
- [Examples](#examples)
## Authentication
The API uses RapidAPI authentication headers. Include these headers in your requests:
```http
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
**Note:** Most endpoints require authentication except for the `renderConfigs` endpoint which uses encrypted URLs for security.
## API Endpoints
### Health Check
**Endpoint:** `GET /youtube/utils/health`
**Description:** Checks the operational status of the API and its connection to downstream services.
**Example:**
```http
GET /youtube/utils/health
```
### YouTube Video Details
**Endpoint:** `GET /youtube/v3/video/details`
**Description:** Extracts comprehensive information about a YouTube video including metadata, available formats, download links, and server-rendered video options with audio merging capabilities.
**Query Parameters:**
- `videoId` (string, required): YouTube video ID (e.g., "dQw4w9WgXcQ")
- `countryCode` (string, optional): ISO country code for geo-specific content (e.g., "us", "gb", "ca")
- `lang` (string, optional): Language code (default: "en-US")
- `renderableFormats` (string, optional): Comma-separated list of quality formats to render (e.g., "720p,1080p,highres"). **Note:** If any videos are rendered, this request will be `billed as 2 requests`. If both this parameter, `getTranscript='true'` and `urlAccess='proxied'` are used, the total cost remains 2 requests (charges do not stack).
- `urlAccess` (string, optional): Determines how video and audio URLs are accessed. When set to `proxied`, the API uses its own proxies to prevent 403 errors, which can sometimes occur with `normal` URLs. This comes at the cost of slower download speeds, and each request made with `proxied` is `billed as 2 requests`. Can be `normal` (direct URLs) or `proxied` (URLs are proxied through the API). Defaults to `proxied`. **Note:** If both this parameter, `getTranscript='true'` and `renderableFormats` are used, the total cost remains 2 requests (charges do not stack).
- `getTranscript` (string, optional): Set to "true" to retrieve the video transcript. If a transcript was successfully gotten, the request will be `billed as 2 requests`. **Note:** If both this parameter, `urlAccess` and `renderableFormats` are used, the total cost remains 2 requests (charges do not stack).
- `transcriptLanguage` (string, optional): The desired language for the transcript. This must be one of the languages returned in the `metadata.transcript.languages` array. If not provided, the default transcript is returned.
- `fields` (string, optional): A comma-separated list of fields to include in the response. This can be used to limit the amount of data returned. See [Allowed Fields](#allowed-fields) for a list of available fields. For exclusion, prefix the field with a dash; e.g. `-metadata`, `-contents.audios`
**Required Headers:**
- `X-RapidAPI-Key: YOUR_API_KEY`
- `X-RapidAPI-Host: your-rapidapi-host.rapidapi.com`
**Response Structure:**
```json
{
"error": null,
"contents": [
{
"videos": [
{
"label": "720p",
"url": "https://api.example.com/youtube/utils/redirector?url_token=...",
"hashId": "abc123...",
"metadata": {
"itag": 22,
"mime_type": "video/mp4; codecs=\"avc1.64001F, mp4a.40.2\"",
"quality_label": "720p",
"width": 1280,
"height": 720,
"fps": 30,
"content_length_text": "45.2 MB"
}
}
],
"audios": [
{
"label": "medium",
"url": "https://api.example.com/youtube/utils/redirector?url_token=...",
"hashId": "def456...",
"metadata": {
"itag": 140,
"mime_type": "audio/mp4; codecs=\"mp4a.40.2\"",
"audio_quality": "AUDIO_QUALITY_MEDIUM",
"audio_sample_rate": "44100",
"content_length_text": "3.2 MB"
}
}
],
"renderableVideos": [
{
"label": "720p",
"renderConfig": {
"executionUrl": "https://render-api.example.com/api/v1/render/execute/cache_id_123",
"statusUrl": "wss://render-api.example.com/api/v1/render/status/render_id_456"
},
"hashId": "ghi789...",
"metadata": {
"itag": 22,
"mime_type": "video/mp4; codecs=\"avc1.64001F, mp4a.40.2\"",
"quality_label": "720p",
"width": 1280,
"height": 720
}
}
]
}
],
"metadata": {
"title": "Never Gonna Give You Up",
"thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
"author": {
"id": "UCuAXFkgsw1L7xaCfnd5JJOw",
"name": "Rick Astley",
"thumbnails": [...]
},
"transcript": {
"languages": [...],
"selectedLanguage": "en",
"transcript": [...],
"error": null
},
"additionalData": {
"duration": "00:03:33",
"view_count": "1,234,567,890",
"upload_date": "2009-10-25",
"captions": [...],
"storyboards": [...]
}
}
}
```
**Example:**
```http
GET /youtube/v3/video/details?videoId=dQw4w9WgXcQ&renderableFormats=720p,1080p&countryCode=us&getTranscript=true&transcriptLanguage=en
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
### Renderable Formats
The `renderableFormats` query parameter accepts a comma-separated list of desired video qualities for server-side rendering. The available formats depend on the platform.
#### YouTube
- Specific qualities: `144p`, `144p60 HDR`, `240p`, `240p60 HDR`, `360p`, `360p60 HDR`, `480p`, `480p60 HDR`, `720p`, `720p60`, `720p60 HDR`, `1080p`, `1080p60`, `1080p60 HDR`, `1440p`, `1440p60`, `1440p60 HDR`, `2160p`, `2160p60`, `2160p60 HDR`
- **Dynamic qualities:** `lowres`, `midres`, `highres`, `all`, `all_highres`
#### Instagram & Facebook
- Specific qualities: `144p`, `240p`, `360p`, `480p`, `720p`, `1080p`
- **Dynamic qualities:** `lowres`, `midres`, `highres`, `all`, `all_highres`
### YouTube Video Comments
**Endpoint:** `GET /youtube/v3/video/comments`
**Description:** Retrieves comments for a YouTube video with sorting options and pagination.
**Query Parameters:**
- `videoId` (string, required): YouTube video ID (e.g., "dQw4w9WgXcQ")
- `commentId` (string, optional): The ID of the comment to fetch replies for. If omitted, fetches top-level comments.
- `sortBy` (string, optional): Sort order - `TOP_COMMENTS` or `NEWEST_FIRST`
- `nextToken` (string, optional): Token for paginating through comments
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/video/comments?videoId=dQw4w9WgXcQ&sortBy=TOP_COMMENTS
```
### YouTube Post Details
**Endpoint:** `GET /youtube/v3/post/details`
**Description:** Retrieves details for a YouTube post.
**Query Parameters:**
- `postId` (string, required): YouTube post ID
- `channelId` (string, required): YouTube channel ID
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/post/details?postId=POST_ID&channelId=CHANNEL_ID
```
### YouTube Post Comments
**Endpoint:** `GET /youtube/v3/post/comments`
**Description:** Retrieves comments for a YouTube post with sorting options and pagination.
**Query Parameters:**
- `postId` (string, required): YouTube post ID
- `channelId` (string, required): YouTube channel ID
- `sortBy` (string, optional): Sort order - `TOP_COMMENTS` or `NEWEST_FIRST`
- `nextToken` (string, optional): Token for paginating through comments
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/post/comments?postId=POST_ID&channelId=CHANNEL_ID&sortBy=TOP_COMMENTS
```
### YouTube Channel Details
**Endpoint:** `GET /youtube/v3/channel/details`
**Description:** Retrieves details for a YouTube channel.
**Query Parameters:**
- `channelId` (string, required): YouTube channel ID
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/channel/details?channelId=CHANNEL_ID
```
### YouTube Channel ID from Handle
**Endpoint:** `GET /youtube/v3/channel/id-from-handle`
**Description:** Retrieves the channel ID for a given YouTube handle.
**Query Parameters:**
- `handle` (string, required): YouTube channel handle (e.g., "@MrBeast")
**Example:**
```http
GET /youtube/v3/channel/id-from-handle?handle=@MrBeast
```
### YouTube Channel Videos
**Endpoint:** `GET /youtube/v3/channel/videos`
**Description:** Retrieves videos from a YouTube channel.
**Query Parameters:**
- `channelId` (string, required): YouTube channel ID
- `contentType` (string, required): The type of content to retrieve. Can be `videos`, `shorts`, or `livestreams`.
- `nextToken` (string, optional): Token for paginating through videos.
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/channel/videos?channelId=CHANNEL_ID&contentType=videos
```
### YouTube Channel Playlists
**Endpoint:** `GET /youtube/v3/channel/playlists`
**Description:** Retrieves playlists from a YouTube channel.
**Query Parameters:**
- `channelId` (string, required): YouTube channel ID
- `contentType` (string, required): The type of content to retrieve. Can be `playlists`, `releases`, or `podcasts`.
- `nextToken` (string, optional): Token for paginating through playlists.
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/channel/playlists?channelId=CHANNEL_ID&contentType=playlists
```
### YouTube Channel Posts
**Endpoint:** `GET /youtube/v3/channel/posts`
**Description:** Retrieves posts from a YouTube channel.
**Query Parameters:**
- `channelId` (string, required): YouTube channel ID
- `nextToken` (string, optional): Token for paginating through posts.
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/channel/posts?channelId=CHANNEL_ID
```
### YouTube Hashtag
**Endpoint:** `GET /youtube/v3/hashtag`
**Description:** Retrieves videos for a given hashtag.
**Query Parameters:**
- `tag` (string, required): The hashtag to search for.
- `nextToken` (string, optional): Token for paginating through videos.
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/hashtag?tag=programming
```
### YouTube Playlists
**Endpoint:** `GET /youtube/v3/playlist`
**Description:** Extracts playlist information and a paginated list of its videos.
**Query Parameters:**
- `playlistId` (string, required): YouTube playlist ID.
- `nextToken` (string, optional): Token for paginating through videos.
- `countryCode` (string, optional): ISO country code for geo-specific content (e.g., "us", "gb", "ca")
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/playlist?playlistId=PLrAXtmRdnEQy6nuLMt20JyowgskgQGfXH
```
### YouTube Search
#### General Search
**Endpoint:** `GET /youtube/v3/search`
**Description:** Search across all YouTube content types (videos, channels, playlists).
#### Specific Search Endpoints
- `GET /youtube/v3/search/video` - Search only videos
- `GET /youtube/v3/search/channel` - Search only channels
- `GET /youtube/v3/search/playlist` - Search only playlists
- `GET /youtube/v3/search/movie` - Search only movies
**Query Parameters:**
- `query` (string, required): Search terms
- `sortBy` (string, optional): **DEPRECATED**. Sort order - `rating`, `relevance`, `upload_date`, `view_count`. Please use `prioritize` and `uploadDate` instead.
- `uploadDate` (string, optional): Filter results by upload date. Can be `all`, `month`, `week`, `year`, or `today`. Defaults to `all`.
- `prioritize` (string, optional): Prioritize results by relevance or popularity. Can be `relevance` or `popularity`. Defaults to `relevance`.
- `duration` (string, optional): Filter results by video duration. Can be `all`, `over_twenty_mins`, `three_to_twenty_mins`, or `under_three_mins`. Defaults to `all`.
- `features` (string, optional): A comma-separated list of video features to filter by. Allowed values: `360`, `3d`, `4k`, `creative_commons`, `hd`, `hdr`, `live`, `location`, `purchased`, `subtitles`, `vr180`.
- `nextToken` (string, optional): Token for paginating through search results.
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/search/video?query=programming+tutorial&prioritize=popularity
```
#### Search Suggestions
**Endpoint:** `GET /youtube/v3/search/suggestions`
**Description:** Get YouTube search suggestions for a query.
**Query Parameters:**
- `query` (string, required): Partial search query
- `previousQuery` (string, optional): Previous search context
- `lang` (string, optional): Language preference for localized content
**Example:**
```http
GET /youtube/v3/search/suggestions?query=javascript
```
### Allowed Fields
The following fields can be used with the `fields` query parameter on the YouTube Video Details endpoint:
- `contents`
- `contents.videos`
- `contents.audios`
- `contents.images`
- `contents.renderableVideos`
- `contents.renderableAudios`
- `metadata`
- `metadata.author`
- `metadata.comments`
- `metadata.playlist`
- `metadata.channel`
- `metadata.post`
- `metadata.hashtag`
- `metadata.transcript`
- `metadata.additionalData`
### Instagram API Endpoints
#### Instagram Media Post Details
**Endpoint:** `GET /instagram/v3/media/post/details`
**Description:** Retrieves the media post for a given Instagram shortcode.
**Query Parameters:**
- `shortcode` (string, required): The Instagram shortcode to look up.
- `renderableFormats` (string, optional): Comma-separated list of quality formats to render. See [Renderable Formats](#renderable-formats) for available options.
**Example:**
```http
GET /instagram/v3/media/post/details?shortcode=C0j2L9yS9-Z
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
#### Instagram User ID from Username (Price:5)
**Endpoint:** `GET /instagram/v3/user/profile/id-from-username`
**Description:** Retrieves the user ID for a given Instagram username.
**Query Parameters:**
- `username` (string, required): The Instagram username to look up.
**Example:**
```http
GET /instagram/v3/user/profile/id-from-username?username=instagram
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
#### Instagram User Profile Details (Price:5)
**Endpoint:** `GET /instagram/v3/user/profile/details`
**Description:** Retrieves the profile details for a given Instagram username.
**Query Parameters:**
- `username` (string, required): The Instagram username to look up.
**Example:**
```http
GET /instagram/v3/user/profile/details?username=instagram
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
### Facebook API Endpoints
#### Facebook Post Details
**Endpoint:** `GET /facebook/v3/post/details`
**Description:** Retrieves the media and metadata for a given Facebook post URL.
**Query Parameters:**
- `url` (string, required): The URL of the Facebook post.
- `renderableFormats` (string, optional): Comma-separated list of quality formats to render. See [Renderable Formats](#renderable-formats) for available options.
**Example:**
```http
GET /facebook/v3/post/details?url=https://www.facebook.com/watch/?v=1234567890
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
#### Facebook Profile Details
**Endpoint:** `GET /facebook/v3/profile/details`
**Description:** Retrieves the profile details for a given Facebook profile URL.
**Query Parameters:**
- `url` (string, required): The URL of the Facebook profile.
**Example:**
```http
GET /facebook/v3/profile/details?url=https://www.facebook.com/zuck
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
#### Facebook Profile ID
**Endpoint:** `GET /facebook/v3/profile/id`
**Description:** Retrieves the profile ID for a given Facebook profile URL.
**Query Parameters:**
- `url` (string, required): The URL of the Facebook profile.
**Example:**
```http
GET /facebook/v3/profile/id?url=https://www.facebook.com/zuck
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
#### Facebook Profile About
**Endpoint:** `GET /facebook/v3/profile/about`
**Description:** Retrieves the "about" information for a given Facebook profile URL.
**Query Parameters:**
- `url` (string, required): The URL of the Facebook profile.
**Example:**
```http
GET /facebook/v3/profile/about?url=https://www.facebook.com/zuck
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
#### Facebook Profile Reels
**Endpoint:** `GET /facebook/v3/profile/reels`
**Description:** Retrieves the reels from a given Facebook profile URL.
**Query Parameters:**
- `url` (string, required): The URL of the Facebook profile.
**Example:**
```http
GET /facebook/v3/profile/reels?url=https://www.facebook.com/zuck
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
#### Facebook Profile Photos
**Endpoint:** `GET /facebook/v3/profile/photos`
**Description:** Retrieves the photos from a given Facebook profile URL.
**Query Parameters:**
- `url` (string, required): The URL of the Facebook profile.
**Example:**
```http
GET /facebook/v3/profile/photos?url=https://www.facebook.com/zuck
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
### TikTok API Endpoints
#### TikTok User Details
**Endpoint:** `GET /tiktok/v3/user/details`
**Description:** Retrieves the profile details for a given TikTok user URL.
**Query Parameters:**
- `url` (string, required): The URL of the TikTok user profile.
**Example:**
```http
GET /tiktok/v3/user/details?url=https://www.tiktok.com/@username
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
#### TikTok Post Details
**Endpoint:** `GET /tiktok/v3/post/details`
**Description:** Retrieves the media and metadata for a given TikTok post URL.
**Query Parameters:**
- `url` (string, required): The URL of the TikTok post.
**Example:**
```http
GET /tiktok/v3/post/details?url=https://www.tiktok.com/@username/video/1234567890
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: your-rapidapi-host.rapidapi.com
```
## RenderConfig Usage Guide
### What are RenderConfigs?
RenderConfigs are server-side video processing configurations that enable advanced video operations like:
- **Audio-Video Merging**: Combining separate video and audio streams into a single MP4 file
- **Quality Enhancement**: Server-side processing for better compression and quality
- **Format Conversion**: Converting between different video formats and codecs
### Understanding RenderConfig Structure
When you request `renderableVideos` in the video-details endpoint, each renderable video contains a `renderConfig` object:
```json
{
"renderConfig": {
"executionUrl": "https://render-api.example.com/api/v1/render/execute/cache_id_abc123",
"statusUrl": "wss://render-api.example.com/api/v1/render/status/render_id_def456"
}
}
```
### RenderConfig Properties
| Property | Type | Description |
| -------------- | ------ | ------------------------------------------------ |
| `executionUrl` | string | HTTP endpoint to trigger the rendering process |
| `statusUrl` | string | WebSocket endpoint to monitor rendering progress |
### How to Use RenderConfigs
#### Step 1: Request Video with Renderable Formats
```bash
curl -X GET "https://api.example.com/youtube/v3/video/details?videoId=dQw4w9WgXcQ&renderableFormats=720p,1080p" \
-H "X-RapidAPI-Key: YOUR_API_KEY" \
-H "X-RapidAPI-Host: your-rapidapi-host.rapidapi.com"
```
#### Step 2: Extract RenderConfig from Response
```json
{
"contents": [
{
"renderableVideos": [
{
"label": "720p",
"renderConfig": {
"executionUrl": "https://render-api.example.com/api/v1/render/execute/cache_id_abc123",
"statusUrl": "wss://render-api.example.com/api/v1/render/status/render_id_def456"
},
"hashId": "video_hash_123",
"metadata": {
"quality_label": "720p",
"width": 1280,
"height": 720
}
}
]
}
]
}
```
#### Step 3: Trigger Rendering Process
**Execute the render:**
```bash
# This endpoint does not require authentication
curl "https://render-api.example.com/api/v1/render/execute/cache_id_abc123"
```
**Response:**
```json
{
"success": true,
"renderId": "render_id_def456",
"status": "processing",
"estimatedTime": "30-60 seconds"
}
```
#### Step 4: Monitor Progress (WebSocket)
```javascript
const socket = new WebSocket(
"wss://render-api.example.com/api/v1/render/status/render_id_def456"
);
socket.onmessage = function (event) {
const progress = JSON.parse(event.data);
console.log("Rendering progress:", progress);
if (progress.status === "done") {
console.log("Download URL:", progress.output.url);
socket.close();
}
};
```
**Progress Events:**
```json
// Job not found (initial state)
{
"id": "042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba",
"status": "not_found",
"error": "Job with ID '042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba' not found."
}
// Downloading inputs phase
{
"id": "042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba",
"status": "downloading_inputs",
"progress": null,
"lastModified": 1751359496951,
"createdAt": 1751359496130,
"expiresAt": 1751363096130
}
// Downloading progress updates
{
"id": "042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba",
"status": "downloading_inputs",
"progress": 15,
"lastModified": 1751359503362,
"createdAt": 1751359496130,
"expiresAt": 1751363096130
}
{
"id": "042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba",
"status": "downloading_inputs",
"progress": 70,
"lastModified": 1751359519373,
"createdAt": 1751359496130,
"expiresAt": 1751363096130
}
// Processing phase
{
"id": "042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba",
"status": "processing",
"progress": 0,
"lastModified": 1751359520746,
"createdAt": 1751359496130,
"expiresAt": 1751363096130
}
// Uploading output phase
{
"id": "042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba",
"status": "uploading_output",
"progress": 0,
"lastModified": 1751359522463,
"createdAt": 1751359496130,
"expiresAt": 1751363096130
}
{
"id": "042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba",
"status": "uploading_output",
"progress": 100,
"lastModified": 1751359523280,
"createdAt": 1751359496130,
"expiresAt": 1751363096130
}
// Completion with download URL
{
"id": "042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba",
"status": "done",
"progress": 100,
"lastModified": 1751359525101,
"createdAt": 1751359496130,
"expiresAt": 1751363096130,
"output": {
"url": "https://spvd-render-api-v3.48ebfbc94fea058814361fdda24c0663.r2.cloudflarestorage.com/renders/042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba/042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=fa19a290f67b64e4dfd50674c440c062%2F20250701%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250701T084525Z&X-Amz-Expires=3571&X-Amz-Signature=7a6909d4f1f9101ccd3ddca7572668c22e838e5cc207e38f2b8e9402c6a6d4b0&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject",
"key": "renders/042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba/042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba.mp4"
}
}
```
#### Step 5: Download Rendered Video
```bash
# Download the final rendered video using the URL from the WebSocket response
curl -o "video.mp4" "https://spvd-render-api-v3.48ebfbc94fea058814361fdda24c0663.r2.cloudflarestorage.com/renders/042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba/042b2bb45b655a3adb0e8d71f7f93949265dd0dae8af685d05b39625a5acb9ba.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=fa19a290f67b64e4dfd50674c440c062%2F20250701%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250701T084525Z&X-Amz-Expires=3571&X-Amz-Signature=7a6909d4f1f9101ccd3ddca7572668c22e838e5cc207e38f2b8e9402c6a6d4b0&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject"
```
### Rendering Process Details
#### What Happens During Rendering?
1. **Source Download**: The render service downloads the original video and audio streams
2. **Quality Processing**: Video is processed for optimal quality and compression
3. **Audio Merging**: Separate audio track is merged with video track
4. **Format Optimization**: Final MP4 is optimized for streaming and compatibility
5. **CDN Upload**: Rendered video is uploaded to CDN for fast delivery
#### Rendering Timeline
- **Queue Time**: 0-5 seconds (depending on server load)
- **Processing Time**: 30-120 seconds (depends on video length and quality)
- **Total Time**: Usually completes within 2 minutes for most videos
#### File Lifecycle
- **Render Cache**: Successful renders are cached for 1 hour
- **CDN Storage**: Rendered files are available for download for 1 hour
- **Automatic Cleanup**: Files are automatically deleted after expiration
### Error Handling
#### Retry Logic
```javascript
function pollRenderStatus(statusUrl, maxAttempts = 60) {
return new Promise((resolve, reject) => {
const socket = new WebSocket(statusUrl);
let attempts = 0;
socket.onmessage = function (event) {
const progress = JSON.parse(event.data);
if (progress.status === "done") {
resolve(progress.output.url);
socket.close();
} else if (progress.status === "failed" || progress.error) {
reject(new Error(progress.error || "Rendering failed"));
socket.close();
} else if (++attempts >= maxAttempts) {
reject(new Error("Rendering timeout"));
socket.close();
}
};
socket.onerror = function (error) {
reject(error);
};
});
}
```
### Best Practices
1. **Always monitor progress**: Use WebSocket connection to track rendering status
2. **Handle timeouts gracefully**: Set reasonable timeout limits (2-3 minutes)
3. **Cache download URLs**: Store completed render URLs for the duration of their validity
4. **Implement retry logic**: Retry failed renders with exponential backoff
5. **Download promptly**: Download rendered videos before they expire (1 hour)
## Request Parameters
### Common Parameters
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | -------------------------------------------------------- |
| `countryCode` | string | No | ISO 3166-1 alpha-2 country code for geo-specific content |
| `lang` | string | No | IETF language tag (default: "en-US") |
### Country Codes
Supported values include: `us`, `ca`, `gb`, `de`, `fr`, `jp`, `au`, and many others. Use `worldwide` for global content.
## Response Format
All API responses follow a consistent structure:
```json
{
"error": null | {
"message": "Error description",
"code": "error_code",
"statusCode": 400
},
"contents": [/* Array of Extracted media content */],
"metadata": {/* Content metadata and additional information */}
}
```
### Media Items
Each media item contains:
- `label`: Quality or format description
- `url`: Direct download URL (encrypted for security)
- `hashId`: Unique identifier
- `metadata`: Technical details (codec, bitrate, dimensions, etc.)
### Renderable Items
For server-rendered content:
- `label`: Quality description
- `renderConfig`: Server rendering endpoints
- `hashId`: Unique identifier
- `metadata`: Technical specifications
## Error Handling
The API uses structured error responses with specific error codes:
| Error Code | Description |
| ---------------------- | ---------------------------------------- |
| `invalid_user_details` | Invalid user details provided |
| `invalid_json_body` | Invalid JSON in request body |
| `invalid_params` | Invalid parameter values |
| `signin_required` | Video requires authentication |
| `not_found` | Resource not found |
| `params_not_found` | Required parameters missing |
| `var_not_found` | Environment variable not found |
| `body_not_found` | Request body is missing |
| `encryption_failed` | Failed to encrypt data |
| `decryption_failed` | Failed to decrypt data |
| `token_expired` | Access token has expired |
| `non_2xx_response` | External API returned a non-2xx response |
| `connection_error` | Could not connect to external service |
| `operation_timeout` | Asynchronous operation timed out |
| `foreign_error` | An error occurred in a foreign module |
| `unexpected_error` | Internal server error |
## Rate Limiting & Subscription Tiers
### Subscription Tiers
| Tier | Renderable Formats | Features |
| ----- | -------------------------- | ------------------------ |
| BASIC | 1 format / <=500 MB | Basic video extraction |
| PRO | 3 formats / each <=1 GB | Enhanced quality options |
| ULTRA | 6 formats / each <=1.5 GB | High-quality rendering |
| MEGA | 10 formats / each <=2.5 GB | Full feature access |
## Examples
### Basic Video Information
```bash
curl -X GET "https://api.example.com/youtube/v3/video/details?videoId=dQw4w9WgXcQ" \
-H "X-RapidAPI-Key: YOUR_API_KEY" \
-H "X-RapidAPI-Host: your-rapidapi-host.rapidapi.com"
```
### Search with Filters
```bash
curl -X GET "https://api.example.com/youtube/v3/search/video?query=machine+learning&uploadDate=month&countryCode=us" \
-H "X-RapidAPI-Key: YOUR_API_KEY" \
-H "X-RapidAPI-Host: your-rapidapi-host.rapidapi.com"
```
### Get Playlist Contents
```bash
curl -X GET "https://api.example.com/youtube/v3/playlist?playlistId=PLrAXtmRdnEQy6nuLMt20JyowgskgQGfXH" \
-H "X-RapidAPI-Key: YOUR_API_KEY" \
-H "X-RapidAPI-Host: your-rapidapi-host.rapidapi.com"
```
### Server-Rendered Video
```bash
# 1. Get video info with renderable formats
curl -X GET "https://api.example.com/youtube/v3/video/details?videoId=dQw4w9WgXcQ&renderableFormats=1080p" \
-H "X-RapidAPI-Key: YOUR_API_KEY" \
-H "X-RapidAPI-Host: your-rapidapi-host.rapidapi.com"
# 2. Use the renderConfig.executionUrl from response to trigger rendering (no auth needed)
# 3. Monitor progress via renderConfig.statusUrl (WebSocket)
# 4. Download when rendering completes
```
---
**Note:** This API includes advanced proxy routing, video rendering capabilities, and comprehensive caching for optimal performance. All video URLs are encrypted for security and have limited-time validity.
ance. All video URLs are encrypted for security and have limited-time validity.