RESTful API Documentation

This page documents the main RESTful API endpoints of KCTube/VideoStreamHub.

General Notes

• All endpoints are relative to the server root (e.g. /api/...).
• All responses are in JSON format unless otherwise noted.

Endpoints Overview

Method	Endpoint	Description
GET	/api/config	Get current configuration
POST	/api/config	Update configuration
POST	/api/config/reset	Reset configuration to default
GET	/api/search?q=...	Search YouTube videos
POST	/api/video-info	Get video info by URL
GET	/api/video/<video_id>	Get video info and streaming URLs by ID
POST	/api/download	Download video by URL
GET	/api/local/videos	List local videos (paginated)
GET	/api/local/videos/<video_id>	Get local video by ID
GET	/api/local/videos/<video_id>/stream	Stream local video file
GET	/api/local/videos/<video_id>/subtitle	Get subtitle for local video
GET	/api/movies/scenes	List movie scenes/categories
GET	/api/movies/scenes/<scene_name>/videos	List videos in a movie scene
GET	/api/movies/search?q=...	Search movies
GET	/api/movies/all	List all movies
GET	/api/movies/video/<video_id>	Get movie video by ID
GET	/api/movies/stream/<video_id>	Stream movie video by ID
GET	/api/playlists	List all playlists
POST	/api/playlists	Create a new playlist
GET	/api/playlists/stats	Get playlist statistics
GET	/api/subtitles/<video_id>	Get subtitles for a video
GET	/api/update/yt-dlp/version	Get yt-dlp version
POST	/api/update/yt-dlp	Update yt-dlp
GET	/api/update/check	Check for available updates

Endpoint Details & Examples

1. Search YouTube Videos

GET /api/search?q=your+query[&max_results=24][&page=1]

• q (string, required): Search keyword.
• max_results (int, optional): Number of results per page (default: 24).
• page (int, optional): Page number (default: 1).

Example request:

curl "http://localhost:5000/api/search?q=music&max_results=5&page=1"

Example response:

{
  "videos": [
    {
      "id": "abc123",
      "title": "Music Video Title",
      "author": "Uploader Name",
      "thumbnail": "https://...jpg",
      "duration": "3:45",
      "stats": "1.2M lượt xem"
    },
    ...
  ],
  "total": 100,
  "has_more": true
}

2. Get Video Info by URL

POST /api/video-info

• Body (JSON): { "url": "https://youtube.com/watch?v=..." }

Example request:

curl -X POST http://localhost:5000/api/video-info \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=abc123"}'

Example response:

{
  "id": "abc123",
  "title": "Music Video Title",
  "description": "...",
  "thumbnail": "https://...jpg",
  "uploader": "Uploader Name",
  "upload_date": "20240101",
  "duration": 225,
  "duration_formatted": "3:45",
  "view_count": 1234567,
  "formats": [
    { "quality": "720p", "url": "...", ... }, ...
  ],
  "webpage_url": "https://youtube.com/watch?v=abc123",
  "video_url": "...",
  "audio_url": "..."
}

3. List Local Videos

GET /api/local/videos[?page=1][&per_page=24][&search=keyword]

• page (int, optional): Page number (default: 1).
• per_page (int, optional): Results per page (default: 24).
• search (string, optional): Search keyword for local videos.

Example request:

curl "http://localhost:5000/api/local/videos?page=1&per_page=2"

Example response:

{
  "videos": [
    {
      "id": "local_1",
      "title": "My Local Video",
      "path": "/downloads/myvideo.mp4",
      ...
    },
    ...
  ],
  "total": 10,
  "page": 1,
  "per_page": 2,
  "total_pages": 5
}

Other Endpoints

See the table above for a full list. Most endpoints follow RESTful conventions and return JSON. For more details, see the source code or contact the maintainer.