0
# Core API Functions
1

2
The main API class providing all functionality for retrieving YouTube transcripts. Supports proxy configuration, custom HTTP clients, language selection, and formatting options.
3

4
## Capabilities
5

6
### YouTubeTranscriptApi Class
7

8
Main entry point for all transcript retrieval operations. Provides both simple one-step transcript fetching and detailed transcript list management.
9

10
```python { .api }
11
class YouTubeTranscriptApi:
12
    def __init__(self, proxy_config=None, http_client=None):
13
        """
14
        Initialize the YouTube Transcript API client.
15

16
        Args:
17
            proxy_config (ProxyConfig, optional): Proxy configuration for network requests
18
            http_client (requests.Session, optional): Custom HTTP client session
19

20
        Note:
21
            Not thread-safe due to requests.Session usage. Create separate instances per thread.
22
        """
23

24
    def fetch(self, video_id, languages=("en",), preserve_formatting=False):
25
        """
26
        Retrieve transcript for a single video (shortcut method).
27

28
        Args:
29
            video_id (str): YouTube video ID (not full URL)
30
            languages (tuple, optional): Language codes in priority order. Defaults to ("en",)
31
            preserve_formatting (bool, optional): Whether to keep HTML formatting. Defaults to False
32

33
        Returns:
34
            FetchedTranscript: The retrieved transcript with content
35

36
        Raises:
37
            VideoUnavailable: Video is no longer available
38
            TranscriptsDisabled: Subtitles are disabled for this video
39
            NoTranscriptFound: No transcript found for requested languages
40
            RequestBlocked: Requests blocked by YouTube (IP ban)
41
            InvalidVideoId: Invalid video ID provided
42
        """
43

44
    def list(self, video_id):
45
        """
46
        Get list of all available transcripts for a video.
47

48
        Args:
49
            video_id (str): YouTube video ID (not full URL)
50

51
        Returns:
52
            TranscriptList: Container with all available transcripts
53

54
        Raises:
55
            VideoUnavailable: Video is no longer available
56
            TranscriptsDisabled: Subtitles are disabled for this video
57
            RequestBlocked: Requests blocked by YouTube (IP ban)
58
            InvalidVideoId: Invalid video ID provided
59
        """
60
```
61

62
### Usage Examples
63

64
#### Basic Transcript Retrieval
65

66
```python
67
from youtube_transcript_api import YouTubeTranscriptApi
68

69
# Simple transcript fetch with default English
70
api = YouTubeTranscriptApi()
71
transcript = api.fetch('dQw4w9WgXcQ')
72

73
for snippet in transcript:
74
    print(f"[{snippet.start:.2f}s] {snippet.text}")
75
```
76

77
#### Language Priority and Fallbacks
78

79
```python
80
from youtube_transcript_api import YouTubeTranscriptApi
81

82
api = YouTubeTranscriptApi()
83

84
# Try Spanish first, then English as fallback
85
transcript = api.fetch('dQw4w9WgXcQ', languages=['es', 'en'])
86

87
# Or use the list method for more control
88
transcript_list = api.list('dQw4w9WgXcQ')
89
transcript = transcript_list.find_transcript(['es', 'en'])
90
fetched = transcript.fetch()
91
```
92

93
#### Proxy Configuration
94

95
```python
96
from youtube_transcript_api import YouTubeTranscriptApi
97
from youtube_transcript_api.proxies import GenericProxyConfig
98

99
# Configure generic proxy
100
proxy_config = GenericProxyConfig(
101
    http_url='http://proxy:8080',
102
    https_url='https://proxy:8080'
103
)
104

105
api = YouTubeTranscriptApi(proxy_config=proxy_config)
106
transcript = api.fetch('dQw4w9WgXcQ')
107
```
108

109
#### Custom HTTP Client
110

111
```python
112
from youtube_transcript_api import YouTubeTranscriptApi
113
import requests
114

115
# Use custom session with timeout
116
session = requests.Session()
117
session.timeout = 30
118

119
api = YouTubeTranscriptApi(http_client=session)
120
transcript = api.fetch('dQw4w9WgXcQ')
121
```
122

123
#### Preserve HTML Formatting
124

125
```python
126
from youtube_transcript_api import YouTubeTranscriptApi
127

128
api = YouTubeTranscriptApi()
129
transcript = api.fetch('dQw4w9WgXcQ', preserve_formatting=True)
130

131
# Text may contain HTML tags like <b>, <i>, etc.
132
for snippet in transcript:
133
    print(snippet.text)  # May include HTML formatting
134
```
135

136
## Types
137

138
```python { .api }
139
from typing import Optional, Iterable
140
from requests import Session
141

142
# Type hints for main API
143
ProxyConfig = Union[GenericProxyConfig, WebshareProxyConfig]
144
LanguageCodes = Iterable[str]
145
```