DEVELOPER REFERENCE

API documentation

Use an AniList ID, choose an episode, and set the audio in the URL.

Quick start

Add the player directly to your page. Change 21 to your anime's AniList ID, 1 to the episode, and sub to dub for dubbed audio.

Responsive iframe

<iframe
  src="https://aniplayer.xyz/embeds/21/1/sub"
  title="Anime player"
  style="width:100%;aspect-ratio:16/9;border:0"
  allow="autoplay; fullscreen; picture-in-picture; encrypted-media"
  allowfullscreen>
</iframe>

The public origins are aniplayer.xyz and kari.anikari.xyz. For local development, use http://localhost:3000.

Endpoints

API routes return JSON. The player route returns the embedded player page.

GET/embeds/{aniId}/{episode}/{lang}

Embedded player

An iframe-ready player with audio fixed by the URL. Episode navigation preserves the chosen language.

Path parameters
Parameter	Type	Description
`aniId`	integer	A positive AniList anime ID.
`episode`	integer	A positive episode number, starting at 1.
`lang`	string	sub for subtitled audio, or dub for dubbed audio.

Example

/embeds/21/1/sub\n/embeds/21/1/dub

GET/api/embeds/{aniId}/{episode}/{lang}

Embed URL and HTML

Returns a relative player URL and iframe HTML. This endpoint does not return a video source URL.

Path parameters
Parameter	Type	Description
`aniId`	integer	A positive AniList anime ID.
`episode`	integer	A positive episode number, starting at 1.
`lang`	string	sub for subtitled audio, or dub for dubbed audio.

The example abbreviates the iframe HTML. Prefix the returned embedUrl with the API origin when embedding it on another site.

Example

{
  "success": true,
  "results": {
    "embedUrl": "/embeds/21/1/dub",
    "iframe": "<iframe src=\"/embeds/21/1/dub\" ...></iframe>",
    "source": "megaplay",
    "server": "primary-mirror",
    "type": "anime",
    "aniId": "21",
    "ep": "1",
    "lang": "dub"
  }
}

GET/api/stream/{aniId}/{episode}/{lang}

Stream sources

Returns proxied HLS sources, subtitle tracks, and available intro/outro markers for the requested language.

Path parameters
Parameter	Type	Description
`aniId`	integer	A positive AniList anime ID.
`episode`	integer	A positive episode number, starting at 1.
`lang`	string	sub for subtitled audio, or dub for dubbed audio.

By default, the initial stream is tried first and a same-language backup mirror is returned if extraction fails. Optional ?provider=primary or ?provider=backup requests just that mirror; ?provider=auto enables automatic fallback.

The response includes a sources array and repeats its first source at the top level of results. Track lists and skip markers depend on the provider; the example URLs and times are illustrative.

Example

{
  "success": true,
  "results": {
    "sources": [
      {
        "server": "primary-mirror",
        "source": "megaplay",
        "lang": "sub",
        "hlsUrl": "https://your-proxy.example/?url=...",
        "tracks": [],
        "intro": { "start": 31, "end": 111 },
        "outro": null
      }
    ],
    "server": "primary-mirror",
    "source": "megaplay",
    "lang": "sub",
    "hlsUrl": "https://your-proxy.example/?url=...",
    "tracks": [],
    "intro": { "start": 31, "end": 111 },
    "outro": null,
    "aniId": "21",
    "ep": "1"
  }
}

GET/api/meta/{aniId}

Anime metadata

Returns AniList metadata: id, title, episode count, cover, color, and banner. The episode count may be null when unavailable.

Path parameters
Parameter	Type	Description
`aniId`	integer	A positive AniList anime ID.

Example

const response = await fetch('/api/meta/21')\nconst { success, results } = await response.json()

GET/api/episodes/{aniId}

Episode list

Returns numbered episodes with id, episode_no, title, description, and image. Descriptions and images can be empty when unavailable.

Path parameters
Parameter	Type	Description
`aniId`	integer	A positive AniList anime ID.

Example

const response = await fetch('/api/episodes/21')\nconst { success, results } = await response.json()\n// results.episodes contains the numbered episode list.

Audio & fallback

The player has no language or server picker. Audio is selected with the final /sub or /dub URL segment. A backup mirror prepares in the background while playback starts. If extraction or media playback fails, the player tries a backup mirror in the same language, retaining the playback position when possible.

A dub request never switches to sub, and a sub request never switches to dub. Provider availability and failure detection determine how long a switch takes.

Older /embeds/{aniId}/{episode} URLs redirect to /sub. The corresponding API routes without a language also default to sub.

Error responses

Check both the HTTP status and the response's success field. Invalid embed or stream IDs, episode numbers, or languages return 400. No requested-language stream returns 404. Metadata and episode lookups can return 404 for unavailable data or 502 if the upstream request fails.

Error shape

{
  "success": false,
  "error": "Stream unavailable"
}