YouTube API Server

A FastAPI-based server providing API endpoints for extracting and processing YouTube video data, including metadata, captions, and timestamps.

Features

• Extract video metadata using YouTube's oEmbed API
• Retrieve video captions/transcripts
• Generate timestamped captions
• Transcript caching with configurable TTL and LRU eviction
• RESTful API with Swagger/OpenAPI documentation
• Service status page and monitoring endpoints
• Docker support for easy deployment

Requirements

• Python 3.8+
• FastAPI
• youtube-transcript-api
• Docker (optional)

Installation

Using Python

1. Clone the repository:

   git clone https://github.com/creativerezz/youtube-api-server.git
   cd youtube-api-server

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Create a .env file from the example:

   cp .env.example .env

5. (Optional) Configure proxy settings in .env for bypassing YouTube restrictions:

   PROXY_TYPE=webshare
   WEBSHARE_USERNAME=your-username
   WEBSHARE_PASSWORD=your-password

6. Run the server:

   python -m app.main

Using Docker

1. Clone the repository:

   git clone https://github.com/creativerezz/youtube-api-server.git
   cd youtube-api-server

2. Build and start the Docker container:

   docker-compose up -d

Usage

Once the server is running, you can access:

• API documentation: http://localhost:8000/docs
• Alternative API documentation: http://localhost:8000/redoc
• Service information page: http://localhost:8000/service/info
• Service status (JSON): http://localhost:8000/service/status

API Endpoints

1. Get Video Metadata

POST /youtube/video-data

Request body:

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Response:

{
  "title": "Video Title",
  "author_name": "Channel Name",
  "author_url": "https://www.youtube.com/channel/...",
  "type": "video",
  "height": 113,
  "width": 200,
  "version": "1.0",
  "provider_name": "YouTube",
  "provider_url": "https://www.youtube.com/",
  "thumbnail_url": "https://i.ytimg.com/vi/..."
}

2. Get Video Captions

POST /youtube/video-captions

Request body:

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "languages": ["en"]
}

Response:

"Text of the captions..."

3. Get Video Timestamps

POST /youtube/video-timestamps

Request body:

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "languages": ["en"]
}

Response:

[
  "0:00 - Caption at the beginning",
  "0:05 - Next caption",
  "0:10 - Another caption"
]

Proxy Configuration

The server supports proxy configuration to bypass YouTube API restrictions. Two proxy types are supported:

Webshare Proxy (Recommended)

Webshare provides rotating residential proxies that work well with YouTube's API:

PROXY_TYPE=webshare
WEBSHARE_USERNAME=your-username
WEBSHARE_PASSWORD=your-password

Generic Proxy

For other proxy providers, use the generic proxy configuration:

PROXY_TYPE=generic
PROXY_URL=http://proxy.example.com:8080
# Or specify separate HTTP/HTTPS proxies:
PROXY_HTTP=http://proxy.example.com:8080
PROXY_HTTPS=https://proxy.example.com:8443

Project Structure

youtube-api-server/
├── app/
│   ├── __init__.py
│   ├── main.py                # FastAPI application initialization
│   ├── models/                # Pydantic models
│   │   ├── __init__.py
│   │   └── youtube.py
│   ├── routes/                # API routes
│   │   ├── __init__.py
│   │   └── youtube.py
│   └── utils/                 # Utility functions
│       ├── __init__.py
│       └── youtube_tools.py
├── .env.example               # Example environment variables
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Docker configuration
└── docker-compose.yml         # Docker Compose configuration

Service Status

Visit /service/info for a beautiful HTML service information page, or /service/status for JSON status data.

Frontend Integration

For frontend developers: See FRONTEND_API.md for complete API documentation with:

• JavaScript/TypeScript code examples
• React and Vue.js hooks
• Error handling patterns
• TypeScript type definitions
• Best practices and testing

Performance Testing

Test transcript fetching performance and cache effectiveness:

# Test local server
python test_transcript_speed.py

# Test production server
python test_transcript_speed.py https://fetch.youtubesummaries.cc

# Test specific videos with custom runs
python test_transcript_speed.py http://localhost:8000 dQw4w9WgXcQ,jNQXAC9IVRw 5

Or use the API endpoint:

curl "https://fetch.youtubesummaries.cc/youtube/performance/test?video=dQw4w9WgXcQ&runs=5"

Changelog

See CHANGELOG.md for a detailed list of changes and version history.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Reza Jafar

• GitHub: @creativerezz
• X (Twitter): @creativerezz

License

This project is licensed under the MIT License - see the LICENSE file for details.