documentation/stream-api/reference/paths.md

Paths & Playback Events

API reference for Stream API endpoints, Server-Sent Events contracts, and proxy query parameters.

Progressive Playback Endpoints

Stream API uses Server-Sent Events (SSE) so players can start buffering as soon as the first candidate source is verified.

---

1. Movie Stream: GET /movie

Establishes an SSE stream for a movie.

GET /movie?id=155 HTTP/1.1
Host: api.vyla.cc
Accept: text/event-stream

Parameters:

• id (number, required) — Numeric TMDB Movie ID (e.g. 155 for The Dark Knight).

---

2. TV Series Stream: GET /tv

Establishes an SSE stream for a television series episode.

GET /tv?id=1396&season=1&episode=1 HTTP/1.1
Host: api.vyla.cc
Accept: text/event-stream

Parameters:

• id (number, required) — Numeric TMDB TV Series ID (e.g. 1396 for Breaking Bad).
• season (number, required) — Season number (e.g. 1).
• episode (number, required) — Episode number (e.g. 1).

---

SSE Event Lifecycle

Connections return Content-Type: text/event-stream and emit events in sequence:

Event 1: meta

Sent immediately with title metadata and subtitle tracks while scrapers are still running.

data: {
  "type": "meta",
  "meta": {
    "title": "The Dark Knight",
    "year": 2008,
    "tmdb_id": 155,
    "imdb_id": "tt0468569",
    "poster": "https://image.tmdb.org/t/p/w500/sample.jpg",
    "backdrop": "https://image.tmdb.org/t/p/original/sample.jpg"
  },
  "subtitles": [
    {
      "label": "English",
      "file": "https://api.vyla.cc/api?url=https%3A%2F%2Fsubtitles.org%2Fen.vtt",
      "type": "vtt",
      "source": "opensubtitles"
    }
  ]
}

Event 2..N: source

Emitted progressively as each provider scraper completes two-phase verification.

data: {
  "type": "source",
  "source": "vidlink",
  "label": "VidLink Primary",
  "url": "https://api.vyla.cc/api?url=https%3A%2F%2Fupstream.cdn%2Fmaster.m3u8&vl=1",
  "server": "vidlink-cf",
  "quality": "1080p",
  "type": "hls",
  "headers": {
    "User-Agent": "Mozilla/5.0 ...",
    "Referer": "https://vidlink.pro/"
  }
}

Event Final: done

Emitted when all enabled scrapers have finished or timed out. The server closes the SSE connection immediately after.

data: {
  "type": "done",
  "total": 5
}

---

Media Reverse Proxy: GET /api

The /api route handles media proxying, M3U8 playlist rewriting, header spoofing, and byte stripping.

GET /api?url=https%3A%2F%2Fcdn.example.com%2Fvideo.m3u8&vl=1 HTTP/1.1

Parameters:

• url (string, required) — URL-encoded target URL to fetch.
• proxyHeaders (string, optional) — URL-encoded JSON object of custom headers to forward.
• <source_flag> (string, optional) — Source flag matching configuration (e.g. &vl=1, &vx=1) to apply source-specific referer rules.
• tt (string, optional) — Forces the 120-byte image header stripping routine on MPEG-TS video chunks.

Proxy Features:

• M3U8 Rewriting: Rewrites all .ts chunk URIs and #EXT-X-KEY AES encryption endpoints to route through the proxy with CORS headers (Access-Control-Allow-Origin: *).
• Obfuscation Stripping: Slices off the 120-byte image header if chunks start with PNG (0x89), JPEG (0xFF), or null (0x00) bytes.
• Range Seeking: Forwards Range: bytes=start-end headers and returns HTTP 206 Partial Content for video seeking.

---

Active Sources Listing: GET /api?sources_meta=1

Returns all provider scrapers currently loaded into the instance:

{
  "sources": [
    { "key": "vidlink", "label": "VidLink", "timeout": 12000 },
    { "key": "vixsrc", "label": "VixSrc", "timeout": 10000 },
    { "key": "cinecat", "label": "CineCat", "timeout": 15000 }
  ]
}

---

HTTP Status Codes

• 200 OK — Request succeeded or SSE stream opened.
• 206 Partial Content — Byte-range media response for video scrubbing.
• 400 Bad Request — Missing parameters or invalid ID ({"error": "missing id"}).
• 404 Not Found — Unknown route ({"error": "not found"}).
• 502 Bad Gateway — Upstream provider connection failed or timed out.