> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vyla.cc/llms.txt
> Use this file to discover all available pages before exploring further.
# Providers
> How streaming providers are selected, verified, and proxied — and how to interpret their behavior in responses.
Vyla API aggregates multiple independent streaming providers. Each has different internal mechanisms, reliability profiles, and timeout characteristics. This page explains what's happening under the hood so you can build smarter applications.
***
## How Providers Are Used
On every `/movie` or `/tv` request:
1. All active (non-disabled) providers are queried **simultaneously** with per-source random jitter to stagger upstream requests
2. Each provider has its own **timeout**, **retry count**, and **backoff delay**
3. Every returned URL is **verified** — first via a HEAD request to the raw upstream URL, then via a proxied HLS playability check
4. Only URLs that pass both verification steps appear in the response as `source` events
Because the endpoint is SSE, **verified sources are emitted immediately as each provider resolves** — your player receives them progressively. The stream closes once every provider has either resolved or timed out.
To see which providers are currently configured and their live status, call [`/api/health`](https://1c34-y.hf.space/api/health). Provider keys, labels, and timeouts are also available via [`GET /api?sources_meta`](https://1c34-y.hf.space/api?sources_meta).
***
## Provider Configuration
Each provider is defined with the following properties:
| Field | Description |
| ---------------- | ------------------------------------------------------------------------------------------- |
| `key` | Internal identifier used in API responses and the `source` field |
| `label` | Human-readable name shown in the `label` field |
| `proxyParam` | Short query parameter used to route proxied requests |
| `timeout` | Maximum time (ms) to wait for a stream URL |
| `sourcesTimeout` | Optional secondary timeout (ms) for an internal source-listing step, used by some providers |
| `jitter` | Max random delay (ms) before the request fires, to stagger upstream hits |
| `retries` | Number of retry attempts on failure |
| `skipProxy` | If `true`, stream URLs are returned as-is without proxy wrapping |
| `disabled` | If `true`, the provider is excluded from all requests |
Providers with `disabled: true` are completely skipped — they won't appear in health checks or fanout responses.
***
## Response Time
The first `source` event typically arrives within **3–8 seconds**. Subsequent sources stream in as each provider resolves. The stream closes once the **slowest configured provider** times out — in the worst case this can be 60+ seconds (e.g. `cinezo` has a 60 s timeout), though most sources emit well before then.
**Best practice:** always show a loading state, begin playback on the first `source` event, and implement a client-side timeout for the overall stream. See the [Error Handling](/guides/error-handling) guide.
***
## Caching
Results are cached in-memory with a **5-minute TTL**. The per-source stream cache is keyed by `source_key + tmdb_id + season + episode`; the aggregate source-results cache is keyed by `tmdb_id + season + episode + base`. Cache hits skip the provider fetch entirely and return near-instantly.
```
CACHE_TTL = 5 minutes
```
The cache resets on server restart. Cache size is reported in the `/api/health` response under the `cache` field.
***
## The HLS Proxy
All provider stream URLs are wrapped in the server proxy (unless `skipProxy: true`):
```
/api?url=&=1
```
When your player fetches this path, the server:
1. Fetches the upstream M3U8 with the correct `Referer`, `Origin`, and any provider-specific headers
2. Rewrites all segment URLs and encryption key URIs in the playlist to route through the same proxy
3. Returns the rewritten playlist with `Access-Control-Allow-Origin: *`
This means **your player never talks to the provider directly** — all HLS traffic flows through the proxy, keeping CORS and rate-limiting issues fully contained.
***
## Stream Verification
Before a URL is emitted as a `source` event, it passes two verification steps:
1. **`verifyStream`** — a HEAD request to the raw upstream URL (skipped for `SKIP_VERIFY` sources). Must return HTTP `< 400`.
2. **`verifyPlayable`** — fetches the proxied URL, validates `#EXTM3U`, checks for `#EXTINF` or `#EXT-X-STREAM-INF`, then fetches the first segment with a range request.
Sources that fail either step — HTTP errors, timeouts, non-HLS/non-MP4 content — are silently dropped. MP4 sources skip the `#EXTM3U` check and are verified via HEAD + content-type inspection instead. HTTP 429 responses and timeout/abort errors are treated as **passing** (stream exists but is rate-limited).
`/test` runs the same two-step verification pipeline as `/movie` and `/tv`. Check the `ok` field in the response body — HTTP status is always `200` regardless of result.
***
## Disabled Providers
Providers marked `disabled: true` in config are completely excluded from:
* `/api/movie` and `/api/tv` fanout
* `/api/health` probes
* `GET /api?sources_meta` listings
If a provider you expect to see is missing from responses, check whether it's been disabled.
***
## Multi-URL Sources
Some providers return multiple candidate stream URLs (via `allUrls`). For these, verification runs through each candidate in order and returns the first one that passes. If none pass, the source is dropped.
For providers with `SKIP_VERIFY`, all candidate URLs are returned as separate source events without verification. These are not distinguished by numbered labels in the response.