documentation/stream-api/reference/media-data.md

Subtitles & Media Downloads

REST API reference for retrieving subtitle tracks and direct media download packages for movies and television series.

Subtitle Endpoints

Stream API provides dedicated REST endpoints to fetch subtitle tracks independently from video streams. Subtitles are discovered and parsed into web-standard .vtt or .srt formats.

---

1. Movie Subtitles

GET /subtitles/movie/:id HTTP/1.1
Host: your-api.example.com

Path Parameters

Parameter	Type	Required	Description
id	integer	Required	Numeric TMDB Movie ID (e.g. 155)

Example Request & Response

curl https://your-api.example.com/subtitles/movie/155

{
  "subtitles": [
    {
      "label": "English",
      "file": "https://your-api.example.com/api?url=https%3A%2F%2Fsubtitles.org%2Fen.vtt",
      "type": "vtt",
      "source": "opensubtitles"
    },
    {
      "label": "Spanish",
      "file": "https://your-api.example.com/api?url=https%3A%2F%2Fsubtitles.org%2Fes.vtt",
      "type": "vtt",
      "source": "opensubtitles"
    },
    {
      "label": "French",
      "file": "https://your-api.example.com/api?url=https%3A%2F%2Fsubtitles.org%2Ffr.srt",
      "type": "srt",
      "source": "subdl"
    }
  ]
}

---

2. Television Episode Subtitles

GET /subtitles/tv/:id/:season/:episode HTTP/1.1
Host: your-api.example.com

Path Parameters

Parameter	Type	Required	Description
id	integer	Required	Numeric TMDB TV Series ID (e.g. 1396)
season	integer	Required	Season number (e.g. 1)
episode	integer	Required	Episode number (e.g. 1)

Example Request

curl https://your-api.example.com/subtitles/tv/1396/1/1

---

Download Endpoints

Stream API resolves high-speed direct media download packages and torrent/debrid links. Download lookups are separated from playback streams to allow offline caching or background download managers.

---

1. Movie Downloads

GET /downloads/movie/:id HTTP/1.1
Host: your-api.example.com

Example Response

{
  "downloads": [
    {
      "quality": "1080p",
      "size": 2450882194,
      "type": "mkv",
      "active": true,
      "url": "https://fast-cdn.example.com/download/the-dark-knight-1080p.mkv"
    },
    {
      "quality": "720p",
      "size": 1150428190,
      "type": "mkv",
      "active": true,
      "url": "https://fast-cdn.example.com/download/the-dark-knight-720p.mkv"
    }
  ]
}

---

2. Television Episode Downloads

GET /downloads/tv/:id/:season/:episode HTTP/1.1
Host: your-api.example.com

Example Response

{
  "downloads": [
    {
      "quality": "1080p",
      "size": 1420882194,
      "type": "mkv",
      "active": true,
      "url": "https://fast-cdn.example.com/download/breaking-bad-s01e01-1080p.mkv"
    }
  ]
}

---

Best Practices for Clients

1. Do Not Block Initial Playback: Initiate subtitle and download queries asynchronously. The video player should start playback immediately on the first candidate stream, and subtitles should be attached dynamically as they arrive.
2. CORS Handling: Subtitle files proxied through /api?url=... are served with Access-Control-Allow-Origin: *, ensuring HTML5 <track> elements load cleanly in cross-origin browser contexts.
3. Format Support: While most modern players prefer .vtt, some tracks are returned in .srt. If your player strictly requires WebVTT, convert SRT timestamps (00:01:20,500 -> 00:01:20.500) client-side before loading.