vndangkhoa/kv-tube
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kv-tube/API_DOCUMENTATION.md

8.7 KiB
Raw Blame History

KV-Tube API Documentation

Base URL

http://127.0.0.1:5002

Endpoints Overview

Endpoint Method Status Description
/ GET ✅ 200 Homepage
/watch?v={video_id} GET ✅ 200 Video player page
/api/search?q={query} GET ✅ 200 Search videos
/api/trending GET ✅ 200 Trending videos
/api/get_stream_info?v={video_id} GET ✅ 200 Get video stream URL
/api/transcript?v={video_id} GET ✅ 200* Get video transcript (rate limited)
/api/summarize?v={video_id} GET ✅ 200* AI summary (rate limited)
/api/history GET ✅ 200 Get watch history
/api/suggested GET ✅ 200 Get suggested videos
/api/related?v={video_id} GET ✅ 200 Get related videos
/api/channel/videos?id={channel_id} GET ✅ 200 Get channel videos
/api/download?v={video_id} GET ✅ 200 Get download URL
/api/download/formats?v={video_id} GET ✅ 200 Get available formats
/video_proxy?url={stream_url} GET ✅ 200 Proxy video stream
/api/save_video POST ✅ 200 Save video to history
/settings GET ✅ 200 Settings page
/my-videos GET ✅ 200 User videos page

*Rate limited by YouTube (429 errors expected)

Detailed Endpoint Documentation

1. Search Videos

Endpoint: GET /api/search?q={query}
Status: ✅ Working

Example Request:

curl "http://127.0.0.1:5002/api/search?q=python%20tutorial"

Example Response:

[
  {
    "id": "K5KVEU3aaeQ",
    "title": "Python Full Course for Beginners",
    "uploader": "Programming with Mosh",
    "thumbnail": "https://i.ytimg.com/vi/K5KVEU3aaeQ/hqdefault.jpg",
    "view_count": 4932307,
    "duration": "2:02:21",
    "upload_date": ""
  }
]

2. Get Stream Info

Endpoint: GET /api/get_stream_info?v={video_id}
Status: ✅ Working

Example Request:

curl "http://127.0.0.1:5002/api/get_stream_info?v=dQw4w9WgXcQ"

Example Response:

{
  "original_url": "https://manifest.googlevideo.com/api/manifest/hls_playlist/...",
  "stream_url": "/video_proxy?url=...",
  "title": "Rick Astley - Never Gonna Give You Up (Official Video)",
  "description": "The official video for Never Gonna Give You Up...",
  "uploader": "Rick Astley",
  "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "view_count": 1730702525,
  "related": [
    {
      "id": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up...",
      "view_count": 1730702525
    }
  ],
  "subtitle_url": null
}

3. Get Trending Videos

Endpoint: GET /api/trending
Status: ✅ Working

Example Request:

curl "http://127.0.0.1:5002/api/trending"

Example Response:

{
  "data": [
    {
      "id": "discovery",
      "title": "You Might Like",
      "icon": "compass",
      "videos": [
        {
          "id": "GKWrOLrp80c",
          "title": "Best of: Space Exploration",
          "uploader": "The History Guy",
          "view_count": 205552,
          "duration": "1:02:29"
        }
      ]
    }
  ]
}

4. Get Channel Videos

Endpoint: GET /api/channel/videos?id={channel_id}
Status: ✅ Working

Supports:

  • Channel ID: UCuAXFkgsw1L7xaCfnd5JJOw
  • Channel URL: https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw
  • Channel Handle: @ProgrammingWithMosh

Example Request:

curl "http://127.0.0.1:5002/api/channel/videos?id=@ProgrammingWithMosh&limit=5"

Example Response:

[
  {
    "id": "naNcmnKskUE",
    "title": "Top 5 Programming Languages to Learn in 2026",
    "uploader": "",
    "channel_id": "@ProgrammingWithMosh",
    "view_count": 149264,
    "duration": "11:31",
    "thumbnail": "https://i.ytimg.com/vi/naNcmnKskUE/mqdefault.jpg"
  }
]

5. Get Download URL

Endpoint: GET /api/download?v={video_id}
Status: ✅ Working

Example Request:

curl "http://127.0.0.1:5002/api/download?v=dQw4w9WgXcQ"

Example Response:

{
  "url": "https://rr2---sn-8qj-nbo66.googlevideo.com/videoplayback?...",
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "ext": "mp4"
}

6. Get Download Formats

Endpoint: GET /api/download/formats?v={video_id}
Status: ✅ Working

Example Request:

curl "http://127.0.0.1:5002/api/download/formats?v=dQw4w9WgXcQ"

Example Response:

{
  "success": true,
  "video_id": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up",
  "duration": 213,
  "formats": {
    "video": [
      {
        "quality": "1080p",
        "ext": "mp4",
        "size": "226.1 MB",
        "url": "...",
        "type": "video"
      }
    ],
    "audio": [
      {
        "quality": "128kbps",
        "ext": "mp3",
        "size": "3.2 MB",
        "url": "...",
        "type": "audio"
      }
    ]
  }
}

7. Get Related Videos

Endpoint: GET /api/related?v={video_id}&limit={count}
Status: ✅ Working

Example Request:

curl "http://127.0.0.1:5002/api/related?v=dQw4w9WgXcQ&limit=5"

8. Get Suggested Videos

Endpoint: GET /api/suggested
Status: ✅ Working

Based on user's watch history.

9. Get Watch History

Endpoint: GET /api/history
Status: ✅ Working

Example Request:

curl "http://127.0.0.1:5002/api/history"

Example Response:

[
  {
    "id": "dQw4w9WgXcQ",
    "title": "Rick Astley - Never Gonna Give You Up",
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg"
  }
]

10. Video Proxy

Endpoint: GET /video_proxy?url={stream_url}
Status: ✅ Working

Proxies video streams to bypass CORS and enable seeking.

Example Request:

curl "http://127.0.0.1:5002/video_proxy?url=https://manifest.googlevideo.com/api/manifest/hls_playlist/..."

11. Get Transcript ⚠️ RATE LIMITED

Endpoint: GET /api/transcript?v={video_id}
Status: ⚠️ Working but YouTube rate limits (429)

Example Request:

curl "http://127.0.0.1:5002/api/transcript?v=dQw4w9WgXcQ"

Example Response (Success):

{
  "success": true,
  "video_id": "dQw4w9WgXcQ",
  "transcript": [
    {
      "text": "Never gonna give you up",
      "start": 0.0,
      "duration": 2.5
    }
  ],
  "language": "en",
  "is_generated": true,
  "full_text": "Never gonna give you up..."
}

Example Response (Rate Limited):

{
  "success": false,
  "error": "Could not load transcript: 429 Client Error: Too Many Requests"
}

12. AI Summary ⚠️ RATE LIMITED

Endpoint: GET /api/summarize?v={video_id}
Status: ⚠️ Working but YouTube rate limits (429)

Example Request:

curl "http://127.0.0.1:5002/api/summarize?v=dQw4w9WgXcQ"

Example Response:

{
  "success": true,
  "summary": "Rick Astley's official music video for Never Gonna Give You Up..."
}

Rate Limiting

Current Limits:

  • Search: 30 requests/minute
  • Transcript: 10 requests/minute
  • Channel Videos: 60 requests/minute
  • Download: 20 requests/minute

Note: YouTube also imposes its own rate limits on transcript/summary requests.

Error Codes

Code Meaning Solution
200 Success -
400 Bad Request Check parameters
404 Not Found Verify video ID
429 Rate Limited Wait before retrying
500 Server Error Check server logs

Testing Commands

# Homepage
curl http://127.0.0.1:5002/

# Search
curl "http://127.0.0.1:5002/api/search?q=python"

# Get stream
curl "http://127.0.0.1:5002/api/get_stream_info?v=dQw4w9WgXcQ"

# Get download URL
curl "http://127.0.0.1:5002/api/download?v=dQw4w9WgXcQ"

# Get channel videos
curl "http://127.0.0.1:5002/api/channel/videos?id=UCuAXFkgsw1L7xaCfnd5JJOw"

# Get trending
curl http://127.0.0.1:5002/api/trending

# Get history
curl http://127.0.0.1:5002/api/history

Server Information

  • URL: http://127.0.0.1:5002
  • Port: 5002
  • Mode: Development (Debug enabled)
  • Python: 3.12.9
  • Framework: Flask 3.0.2
  • Rate Limiting: Flask-Limiter enabled

Known Issues

  1. Transcript API (429): YouTube rate limits transcript requests

    • Status: Expected behavior
    • Resolution: Wait 1-24 hours or use VPN
    • Frontend handles gracefully with user messages

  2. CORS Errors: Direct YouTube API calls blocked

    • Status: Expected browser security
    • Resolution: Use KV-Tube proxy endpoints

  3. PWA Install Banner: Chrome requires user interaction

    • Status: Expected behavior
    • Resolution: Manual install via browser menu

Generated: 2026-01-10 Version: KV-Tube 2.0