YouTube API¶

The YouTube API provides endpoints for retrieving transcripts, video metadata, and identifying video types from YouTube videos.

Authentication¶

All YouTube API endpoints require authentication using an API key. Include your API key in the X-API-KEY header of your requests.

curl -X POST "https://magic-meal-kits-xxxxx.run.app/api/v1/youtube/transcript/v2" \
     -H "X-API-KEY: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "video_id": "YtJX6YzY6Q8",
       "format": "json"
     }'

Video¶

Endpoints¶

Get Transcript¶

Enhanced endpoint for retrieving video transcripts with additional options and metadata.

POST `/api/v1/youtube/transcript/v2`¶

Request Body:

{
  "video_url": "https://www.youtube.com/watch?v=YtJX6YzY6Q8",
  "preferred_lang": "en",
  "format": "json",
  "retry_count": 3,
  "retry_interval": 6,
  "with_metadata": true
}

Field	Type	Required	Description
video_url	String	No*	YouTube video URL
video_id	String	No*	YouTube video ID
preferred_lang	String	No	Preferred language code (default: auto-detect)
format	String	No	Output format (json, xml, text) (default: xml)
retry_count	Integer	No	Number of retry attempts (default: 3)
retry_interval	Integer	No	Interval between retries in seconds (default: 6)
with_metadata	Boolean	No	Include video metadata (default: false)

* Either video_url or video_id must be provided.

Example Request:

curl -X POST "https://magic-meal-kits-xxxxx.run.app/api/v1/youtube/transcript/v2" \
     -H "X-API-KEY: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "video_id": "YtJX6YzY6Q8",
       "format": "json",
       "with_metadata": true
     }'

Example Response:

{
  "video_id": "YtJX6YzY6Q8",
  "format": "json",
  "content": "...",
  "retry_info": {
    "total_attempts": 1,
    "failed_attempts": 0,
    "errors": []
  },
  "success": true,
  "metadata": {
    "title": "Video Title",
    "author": "Channel Name",
    "author_url": "https://www.youtube.com/@channel",
    "thumbnail_url": "https://i.ytimg.com/vi/YtJX6YzY6Q8/hqdefault.jpg",
    "channel_id": "UC...",
    "channel_handle": "@channel"
  }
}

Identify Video Type¶

Identifies whether a YouTube video is a regular video or a short.

POST `/api/v1/youtube/videotype`¶

Request Body:

{
  "video_url": "https://www.youtube.com/watch?v=YtJX6YzY6Q8"
}

Field	Type	Required	Description
video_url	String	Yes	YouTube video URL or video ID

Example Request:

curl -X POST "https://magic-meal-kits-xxxxx.run.app/api/v1/youtube/videotype" \
     -H "X-API-KEY: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "video_url": "https://www.youtube.com/watch?v=YtJX6YzY6Q8"
     }'

Example Response:

{
  "video_id": "YtJX6YzY6Q8",
  "type": "video",
  "source_url": "https://www.youtube.com/watch?v=YtJX6YzY6Q8"
}

Error Handling¶

All endpoints return a standard error format:

{
  "success": false,
  "error": "Error message description"
}

Common error codes:

400 Bad Request: Invalid parameters or request body
401 Unauthorized: Missing or invalid API key
404 Not Found: Video or resource not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server-side error

Rate Limiting¶

Some endpoints, such as /api/v1/youtube/transcript/v2, have rate limiting applied. If you exceed the rate limit, you will receive a 429 Too Many Requests response.