docs

API Documentation

Name: YouTube Transcript API & Video Data Extraction
Author: VCyon

Complete reference for the YouTube data API: authentication, endpoints, parameters, and response shapes.

Getting Started

API Key Required

All API requests require authentication using an API key.

Free API Key

Get started with 100 free API calls. No credit card required.

Steps to get your API key:

Sign up for a free account
Navigate to the API Keys section in your dashboard
Generate your first API key
Copy and securely store your API key

Quick Start Example

Quick Start Request

curl --location 'https://api.vcyon.com/v1/youtube/video?videoId=UF8uR6Z6KLc'

Base URL

https://api.vcyon.com

Video Information

Get Video Information

GET

Retrieve comprehensive information about a YouTube video including metadata, statistics, thumbnails, and transcript availability.

Endpoint URL

GET /v1/youtube/video

Parameters

Parameter	Type	Required	Description
`videoId`	string	required	YouTube video identifier. Supports multiple formats for flexibility. Example:`UF8uR6Z6KLc` Supported Formats: •Video ID (11 characters): UF8uR6Z6KLc

Request Examples

Using video ID:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/video?videoId=UF8uR6Z6KLc'

Video Transcript

Get Video Transcript

GET

Extract the full transcript of a YouTube video with precise timestamps and language support.

Endpoint URL

GET /v1/youtube/transcript

Parameters

Parameter	Type	Required	Description
`videoId`	string	required	YouTube video identifier in any supported format. Example:`UF8uR6Z6KLc`
`language`	string	optional	Language code for the transcript (e.g., 'English', 'Japanese', 'Indonesia'). If not specified, returns the default language. Example:`English`

Request Examples

Get default transcript:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/transcript?videoId=UF8uR6Z6KLc'

Get Italian transcript:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/transcript?videoId=UF8uR6Z6KLc&language=Italian'

Video Comments

Get Video Comments

GET

Retrieve top-level comments for a YouTube video with support for different sort orders.

Endpoint URL

GET /v1/youtube/comments

Parameters

Parameter	Type	Required	Description
`videoId`	string	required	YouTube video identifier in any supported format (ID or URL). Example:`UF8uR6Z6KLc`
`sort`	string	required	Sort order for comments. Must be one of 'TOP_COMMENTS' or 'NEWEST_FIRST'. Example:`TOP_COMMENTS`

Request Examples

Get top comments:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/comments?videoId=UF8uR6Z6KLc&sort=TOP_COMMENTS'

Get newest comments:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/comments?videoId=UF8uR6Z6KLc&sort=NEWEST_FIRST'

Channel Information

Get Channel Information

GET

Retrieve comprehensive information about a YouTube channel including metadata, statistics, and thumbnails.

Endpoint URL

GET /v1/youtube/channel

Parameters

Parameter	Type	Required	Description
`id`	string	required	YouTube channel ID (starts with UC) or Channel handle (with or without @), e.g., @MrBeast or channel URL https://www.youtube.com/@MrBeast Example:`UCBJycsmduvYEL83R_U4JriQ` Supported Formats: •Channel ID: UCBJycsmduvYEL83R_U4JriQ •Channel Handle: @MrBeast •Channel URL: https://www.youtube.com/@MrBeast •Channel URL: https://www.youtube.com/channel/UCBJycsmduvYEL83R_U4JriQ

Request Examples

Using channel ID:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/channel?id=UCBJycsmduvYEL83R_U4JriQ'

Using channel handle:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/channel?id=@mkbhd'

Channel Videos

Get Channel Videos

GET

Retrieve a list of videos from a YouTube channel with metadata and pagination support.

Endpoint URL

GET /v1/youtube/channel/videos

Parameters

Parameter	Type	Required	Description
`id`	string	optional	YouTube channel Identifier Example:`UCBJycsmduvYEL83R_U4JriQ` Supported Formats: •Channel ID: UCBJycsmduvYEL83R_U4JriQ •Channel Handle: @MrBeast •Channel URL: https://www.youtube.com/@MrBeast •Channel URL: https://www.youtube.com/channel/UCBJycsmduvYEL83R_U4JriQ

Request Examples

Using channel ID:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/channel/videos?id=UCBJycsmduvYEL83R_U4JriQ'

Using channel handle:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/channel/videos?id=@mkbhd'

Playlist Information

Get Playlist Information

GET

Retrieve information about a YouTube playlist including metadata and video listings.

Endpoint URL

GET /v1/youtube/playlist

Parameters

Parameter	Type	Required	Description
`id`	string	required	YouTube playlist identifier. Supports multiple URL formats. Example:`PLBsP89CPrMeO7uztAu6YxSB10cRMpjgiY` Supported Formats: •Playlist ID: PLBsP89CPrMeO7uztAu6YxSB10cRMpjgiY •Full URL: https://www.youtube.com/playlist?list=PLBsP89CPrMeO7uztAu6YxSB10cRMpjgiY

Request Examples

Get playlist info:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/playlist?id=PLBsP89CPrMeO7uztAu6YxSB10cRMpjgiY'

Playlist Videos

Get Playlist Videos

GET

Retrieve a detailed list of videos from a YouTube playlist with metadata and position information.

Endpoint URL

GET /v1/youtube/playlist/videos

Parameters

Parameter	Type	Required	Description
`id`	string	required	YouTube playlist identifier. Supports multiple URL formats. Example:`PLBsP89CPrMeO7uztAu6YxSB10cRMpjgiY` Supported Formats: •Playlist ID: PLBsP89CPrMeO7uztAu6YxSB10cRMpjgiY •Full URL: https://www.youtube.com/playlist?list=PLBsP89CPrMeO7uztAu6YxSB10cRMpjgiY

Request Examples

Get playlist videos:

cURL Request

curl --location 'https://api.vcyon.com/v1/youtube/playlist/videos?id=PLBsP89CPrMeO7uztAu6YxSB10cRMpjgiY'

TypeScript Interfaces

API Response Envelope

All API responses follow a consistent envelope structure with success status, data payload, and metadata.

ApiResponse Interface

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: any;
  };
  meta: {
    timestamp: string;
    requestId: string;
    version: string;
  };
}

Video Information Interfaces

Complete TypeScript interfaces for video information responses including metadata, thumbnails, and channel details.

VideoInfo Interface

interface VideoInfo {
  id: string;
  title: string;
  author: string;
  description: string;
  thumbnails: Thumbnail[];
  category: string;
  tags: string[];
  duration: number;
  channel: Channel;
  viewCount: number;
  likeCount: number;
  isPrivate: boolean;
  isUnlisted: boolean;
  isFamilySafe: boolean;
  publishDate: PublishDate;
  transcriptLanguages: string[];
  hasTranscripts: boolean;
  captionLanguages: CaptionLanguage[];
  hasCaptions: boolean;
  captionTranslationLanguages: TranslationLanguage[];
}

Supporting Interfaces

interface Thumbnail {
  url: string;
  width: number;
  height: number;
}

interface Channel {
  id: string;
  name: string;
  url: string;
}

interface PublishDate {
  text: string;
  date: string;
}

interface CaptionLanguage {
  languageCode: string;
  languageName: string;
}

interface TranslationLanguage {
  languageCode: string;
  languageName: string;
}

Channel Information Interfaces

TypeScript interfaces for YouTube channel information including metadata, statistics, and thumbnails.

ChannelInfo Interface

interface ChannelInfo {
  id: string;
  title: string;
  description: string;
  url: string;
  vanityUrl: string;
  isFamilySafe: boolean;
  keywords: string[];
  avatars: Thumbnail[];
  thumbnails: Thumbnail[];
  tags: string[];
  isUnlisted: boolean;
  subscriberCount: number;
  viewCount: number;
  joinedDate: string;
  videoCount?: number;
  country?: string;
}

Playlist Information Interfaces

TypeScript interfaces for YouTube playlist information and video listings.

PlaylistInfo Interface

interface PlaylistInfo {
  id: string;
  title: string;
  description: string;
  subtitle: string | null;
  author: PlaylistAuthor;
  videoCount: number;
  viewCount: number;
  lastUpdated: string | null;
}

PlaylistAuthor Interface

interface PlaylistAuthor {
  id: string;
  name: string;
  url: string;
}

Transcript Interfaces

TypeScript interfaces for video transcript data with timing information and language support.

Transcript Interfaces

interface TranscriptData {
  language: string;
  transcriptLanguages: string[];
  hasTranscript: boolean;
  segments: TranscriptSegment[];
}

interface TranscriptSegment {
  start: number;
  end: number;
  text: string;
}

Comments Interfaces

TypeScript interfaces for video comments returned by the /v1/youtube/comments endpoint.

Comments Interfaces

interface CommentAuthor {
  id: string;
  name: string;
  thumbnail: string;
}

interface Comment {
  id: string;
  isPinned: boolean;
  likeCount: number;
  replyCount: number;
  text: string;
  publishedTime: string;
  author: CommentAuthor;
}

interface CommentsResponse {
  comments: Comment[];
}

Video List Interfaces

TypeScript interfaces for video listings from channels and playlists with pagination support.

Video List Interfaces

interface VideoListResponse {
  videos: VideoListItem[];
  pagination?: {
    nextPageToken?: string;
    totalResults?: number;
  };
}

interface VideoListItem {
  id: string;
  title: string;
  description: string;
  thumbnails: Thumbnail[];
  duration: number;
  publishedAt: string;
  viewCount?: number;
  position?: number; // For playlist videos
}

Error Handling

HTTP Status Codes

Standard HTTP status codes returned by the API endpoints.

Status Code Reference

Parameter	Type	Description
`200`	OK	Request successful
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	API key lacks required permissions
`404`	Not Found	Video not found or unavailable
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error occurred
`503`	Service Unavailable	Service temporarily unavailable

Need Help?

Our support team is here to help you integrate and get the most out of the YouTube API.

API Documentation

Getting Started

Free API Key

Steps to get your API key:

Video Information

Endpoint URL

Parameters

Request Examples

Video Transcript

Endpoint URL

Parameters

Request Examples

Video Comments

Endpoint URL

Parameters

Request Examples

Channel Information

Endpoint URL

Parameters

Request Examples

Channel Videos

Endpoint URL

Parameters

Request Examples

Playlist Information

Endpoint URL

Parameters

Request Examples

Playlist Videos

Endpoint URL

Parameters

Request Examples

TypeScript Interfaces

Error Handling

Status Code Reference

Need Help?

Overview

API FAQ

Do I need an API key?

What does one request cost?

Can I get transcripts in different languages?

What input formats are supported?

Can I access private or unlisted content?