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:
- All active (non-disabled) providers are queried simultaneously with per-source random jitter to stagger upstream requests
- Each provider has its own timeout, retry count, and backoff delay
- Every returned URL is verified — first via a HEAD request to the raw upstream URL, then via a proxied HLS playability check
- 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. Provider keys, labels, and timeouts are also available via GET /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 |
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 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.
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=<encoded_stream_url>&<proxyParam>=1
- Fetches the upstream M3U8 with the correct
Referer, Origin, and any provider-specific headers
- Rewrites all segment URLs and encryption key URIs in the playlist to route through the same proxy
- 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:
verifyStream — a HEAD request to the raw upstream URL (skipped for SKIP_VERIFY sources). Must return HTTP < 400.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 probesGET /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. 
