API Documentation

Complete guide to embedding movies and TV shows on your website using VidSrc. One iframe, one URL — no API key, no sign-up required.

⚡

Free forever. Copy an embed URL, drop it in an iframe, and you're live. All domains serve identical content — use any mirror if one is unavailable in your region.

Quick Start

HTML

<iframe
  src="https://vidsrc.io/embed/movie/tt1300854"
  width="100%" height="560"
  frameborder="0" allowfullscreen
></iframe>

HTML

<iframe
  src="https://vidsrc.io/embed/tv/1399/1/1"
  width="100%" height="560"
  frameborder="0" allowfullscreen
></iframe>

Custom Domain

Point your own domain to VidSrc and use it as a player URL — with reduced ads and no player branding.

📉

50% fewer ads Your visitors see half the ad load compared to the default domains.

🏷️

No VidSrc logo The player branding is removed — the player looks completely native to your site.

🌐

Your own URL Embed URLs use your domain — e.g. player.yoursite.com/embed/movie/tt1300854

▶️

Direct autoplay The player opens immediately and starts playing — no play button. This no-click autoplay (autoplay=1) works on custom domains only; the official/default domains always show a play button first.

Setup Tutorial

1

Point your domain DNS to VidSrc

Create a Cloudflare account and add your domain. Then go to DNS → Records and add a CNAME record:

DNS Record

Type:    CNAME
Name:    @  (root domain)
Value:   vidsrc-ip.com
Proxy:   Proxied (orange cloud ON)

📢

The target may change. Always check the Announcements section for the latest value before setting up.

2

Configure SSL in Cloudflare

In your Cloudflare dashboard, go to SSL/TLS → Overview → Configure.

SSL/TLS → Overview → Configure

3

Set SSL mode to Flexible

In the Configure panel, set Custom SSL/TLS to Flexible and click Save.

Off

Flexible ✓

Full

Full (strict)

⚠️

Do not use Full or Full (strict) — the connection to VidSrc's origin must remain on HTTP. Flexible is required.

✅

That's it! Your domain will now work exactly like an official VidSrc domain. Use it in embed URLs the same way: https://yourdomain.com/embed/movie/tt1300854

GET/embed/movie/{id}

Movie Embed

Embed a movie player by providing an IMDB ID. Returns a fully responsive, auto-updated player.

Parameters

ParameterRequiredDescription

{id}YesIMDB ID (starts with tt, e.g. tt1300854) or numeric TMDB ID.

Examples

URL

https://vidsrc.io/embed/movie/tt1300854

HTML

<iframe
  src="https://vidsrc.io/embed/movie/tt1300854"
  width="100%" height="560"
  frameborder="0" allowfullscreen
></iframe>

GET/embed/tv/{id}/{season}/{episode}

ALT/embed/tv/{id}/{season}-{episode}

TV Show Embed

Embed a specific episode, or the whole series with a built-in season/episode picker.

Parameters

ParameterRequiredDescription

{id}YesIMDB ID (e.g. tt0944947) or numeric TMDB ID (e.g. 1399).

{season}OptionalSeason number. Omit season & episode to show the season/episode picker.

{episode}OptionalEpisode number within the season.

Examples

URL

https://vidsrc.io/embed/tv/1399/1/1

HTML

<iframe
  src="https://vidsrc.io/embed/tv/1399/1/1"
  width="100%" height="560"
  frameborder="0" allowfullscreen
></iframe>

💡

Find TMDB IDs at themoviedb.org. Search your show and grab the number from the URL.

📺

/embed/tv/1399 (no season/episode) opens the series with a picker and resumes the last-watched episode and position automatically.

GET/embed/movie?imdb={id}

Query String Format

An alternative way to pass IDs via query string instead of URL path segments. Useful for programmatic URL construction.

Examples

# Movie by IMDB
https://vidsrc.io/embed/movie?imdb=tt1300854

# TV Show by TMDB
https://vidsrc.io/embed/tv?tmdb=1399&season=1&episode=1

# TV Show by IMDB
https://vidsrc.io/embed/tv?imdb=tt0944947&season=1&episode=1

Query Parameters

All embed endpoints support optional query parameters appended to the URL for customization.

Playback

ParameterTypeRequiredDescription

autoplay0 / 1OptionalForce autoplay on (1) or off (0). Direct autoplay (opening straight into the player with no play button) works on custom domains only — the official/default domains always show a play button first, and this param then only controls whether playback starts automatically after that click. Browsers may block unmuted autoplay; the player falls back to muted with an unmute prompt.

autonext0 / 1OptionalTV only. Set 1 to auto-play the next episode when the current one ends (shows an "Up next" countdown). Works for both /embed/tv/{id} (no season/episode) and specific-episode URLs. Off by default.

startAtFloatOptionalStart playback at a specific time in seconds — e.g. startAt=300 starts at 5 minutes.

Subtitles

ParameterTypeRequiredDescription

ds_langStringOptionalDefault subtitle language for auto-selection. Accepts ISO 639-1 codes (e.g. en) or 3-letter codes (e.g. eng). You can pass a comma-separated priority list of up to 3 — e.g. en,fr,de — and the player picks the first language that has a subtitle.

sub_urlURLOptionalLoad your own external subtitle file (.vtt or .srt) as a selectable, auto-applied track. The file is fetched and converted to WebVTT entirely in the viewer's browser — our servers never download it — so the file's host must send CORS headers (Access-Control-Allow-Origin). Must be an https:// URL.

sub_labelStringOptionalDisplay name for the sub_url track (e.g. English). Defaults to “Custom subtitle”.

sub_langStringOptionalLanguage code for the sub_url track (e.g. en).

Examples with Parameters

URL

# Enable autoplay
https://vidsrc.io/embed/movie/tt1300854?autoplay=1

# English subtitles default
https://vidsrc.io/embed/movie/tt1300854?ds_lang=en

# Start at 5 minutes + autoplay
https://vidsrc.io/embed/movie/tt1300854?autoplay=1&startAt=300

# TV: auto-play next episode (whole show, starts at S1E1 / resume)
https://vidsrc.io/embed/tv/tt0944947?autonext=1

Subtitles

VidSrc automatically sources subtitles from multiple providers, plus tracks extracted from the video itself.

💬

Built-in subtitles are automatic — no configuration needed. The player shows every available track and prefers the video-extracted ones. Use ds_lang to set the default language.

Default Language Example

URL

# Default subtitle language: German
https://vidsrc.io/embed/movie/tt1300854?ds_lang=de

# Priority list (max 3): try English, then French, then German —
# the player uses the first language that has a subtitle
https://vidsrc.io/embed/movie/tt1300854?ds_lang=en,fr,de

Custom Remote Subtitle (`sub_url`)

🔒

Your sub_url file is downloaded and converted to WebVTT by the viewer's browser only — our servers never fetch it (so no server IP is exposed to the file's host). Because of that, the host must allow cross-origin requests (send an Access-Control-Allow-Origin header) or the browser will block the download.

URL

# Load a custom .vtt/.srt subtitle track (label + language optional)
https://vidsrc.io/embed/movie/tt1300854?sub_url=https://example.com/subs/en.vtt&sub_label=English&sub_lang=en

Player Events

The player sends postMessage events to the parent window so your page can react to playback state — track progress, auto-load next episodes, save watch history, and more.

Event Payload

JSON

{
  "type": "PLAYER_EVENT",
  "data": {
    "player_info": {
      "imdb":      "tt1300854",   // IMDB ID or null
      "tmdb":      null,          // TMDB ID or null
      "mediaType": "movie",       // "movie" or "tv"
      "season":    null,          // season number (TV only)
      "episode":   null           // episode number (TV only)
    },
    "player_status":   "playing",    // see statuses below
    "player_progress": 125.4,        // current time (seconds)
    "player_duration": 7200          // total duration (seconds)
  }
}

Player Statuses

Status—Fired When

playingPlayback starts/resumes, and every ~5 s during playback (progress updates)

pausedUser pauses the video

completedVideo reaches the end

seekedUser seeks to a different position

Listening for Events

JavaScript

window.addEventListener('message', (event) => {
  if (event.data.type !== 'PLAYER_EVENT') return;
  const { player_info, player_status, player_progress } = event.data.data;

  switch (player_status) {
    case 'playing':
      // Save progress for resume
      localStorage.setItem(`progress_${player_info.imdb || player_info.tmdb}`, player_progress);
      break;
    case 'paused':
      console.log('Paused at', player_progress, 's');
      break;
    case 'completed':
      console.log('Finished');
      break;
  }
});

Auto-load Next Episode

JavaScript

window.addEventListener('message', (event) => {
  if (event.data.type !== 'PLAYER_EVENT') return;
  if (event.data.data.player_status !== 'completed') return;

  const { tmdb, imdb, season, episode } = event.data.data.player_info;
  const id = tmdb || imdb;
  const nextEp = parseInt(episode) + 1;
  document.querySelector('iframe').src =
    `https://vidsrc.io/embed/tv/${id}/${season}/${nextEp}`;
});

Resume Playback

Save and restore a viewer's watch position using player_progress from events and the startAt query parameter.

ParameterRequiredDescription

startAtOptionalStart at this timestamp in seconds — e.g. ?startAt=300 starts at 5 minutes

Save & Restore Example

JavaScript

// Save progress from player events
window.addEventListener('message', (e) => {
  if (e.data.type !== 'PLAYER_EVENT') return;
  const { player_info, player_status, player_progress } = e.data.data;
  if (player_status === 'playing') {
    const id = player_info.imdb || player_info.tmdb;
    localStorage.setItem(`progress_${id}`, player_progress);
  }
});

// Restore position when creating the iframe
const id = 'tt1300854';
const saved = localStorage.getItem(`progress_${id}`);
const src = `https://vidsrc.io/embed/movie/${id}${saved ? `?startAt=${saved}` : ''}`;
document.querySelector('iframe').src = src;

URL — Resume at 5 min

https://vidsrc.io/embed/movie/tt1300854?startAt=300

Latest Content Lists

Paginated JSON feeds of the most recently added movies, TV shows and episodes — 50 results per page, newest first. No API key required.

Endpoint—Returns

/movies/latest/page-{N}.jsonLatest added movies

/tvshows/latest/page-{N}.jsonLatest added TV shows

/episodes/latest/page-{N}.jsonLatest added episodes

URL

https://vidsrc.io/movies/latest/page-1.json

Response

Every response is { "result": [ … ], "pages": <total> }. Walk the whole catalogue by requesting page-1 through page-{pages}.

JSON — movies

{
  "result": [
    {
      "imdb_id": "tt1300854",
      "tmdb_id": "68721",
      "title": "Iron Man 3 2013",
      "embed_url": "https://vidsrc.io/embed/movie?imdb=tt1300854",
      "embed_url_tmdb": "https://vidsrc.io/embed/movie?tmdb=68721",
      "quality": "1080p",
      "time_added": "2026-08-04 20:50:35"
    }
  ],
  "pages": 1833
}

Fields

FieldListsDescription

imdb_idallIMDB id — e.g. tt1300854

tmdb_idallTMDB id (may be null)

titlemovies, tvshowsTitle with year

show_titleepisodesSeries title with year

season, episodeepisodesSeason and episode numbers

embed_urlallReady-to-embed URL (IMDB)

embed_url_tmdballReady-to-embed URL (TMDB) — present when a TMDB id exists

quality, time_addedmovies, episodesBest quality label and when it was added

pagesallTotal number of pages available

🕒

Feeds are cached for ~5 minutes. page-1 holds the newest items; higher page numbers reach further back in time.

Content ID Lists

Download plain-text files containing every IMDB and TMDB ID available on VidSrc. One ID per line, updated daily, served from /ids/ with CORS enabled. Useful for syncing your catalog or building import scripts.

File—Content

movie_imdb.txtAll movie IMDB IDs — format: tt1234567

movie_tmdb.txtAll movie TMDB IDs — format: 385687

tv_imdb.txtAll TV show IMDB IDs — format: tt0944947

tv_tmdb.txtAll TV show TMDB IDs — format: 1399

eps_tmdb.txtAll episode TMDB IDs — format: 314541_1x3

eps_imdb.txtAll episode IMDB IDs — format: tt0944947_1x1

URL

https://vidsrc.io/ids/movie_imdb.txt

📋

ID lists are updated daily. Use them to build import pipelines, keep your catalog in sync, or discover what content is currently available.

API Documentation

Quick Start

Custom Domain

Setup Tutorial

Point your domain DNS to VidSrc

Configure SSL in Cloudflare

Set SSL mode to Flexible

Movie Embed

Parameters

Examples

TV Show Embed

Parameters

Examples

Query String Format

Query Parameters

Playback

Subtitles

Examples with Parameters

Subtitles

Default Language Example

Custom Remote Subtitle (sub_url)

Player Events

Event Payload

Player Statuses

Listening for Events

Auto-load Next Episode

Resume Playback

Save & Restore Example

Latest Content Lists

Response

Fields

Content ID Lists

Custom Remote Subtitle (`sub_url`)