thegame_1980/xui-one-api-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
xui-one-api-docs/xtream-codes-player-api-documentation.md
T
worldofiptvcomandGitHub 709c1ed70a Add files via upload
2025-12-24 16:42:51 +03:00

23 KiB
Raw Permalink Blame History

Xtream Codes API Documentation

Complete API reference for the Xtream Codes Player API.

Table of Contents

Overview

The Xtream Codes Player API provides access to IPTV content including live streams, video on demand (VOD), and electronic program guide (EPG) data.

Available Actions

Action Description Category
(none) Get user account & server info User Info
get_live_categories List all live stream categories Live
get_live_streams List all live channels Live
get_vod_categories List all VOD/movie categories VOD
get_vod_streams List all movies VOD
get_vod_info Get detailed movie information VOD
get_short_epg Get short EPG for a channel EPG
get_simple_data_table Get full EPG listing EPG

Authentication

All API requests require authentication via username and password query parameters.

?username=YOUR_USERNAME&password=YOUR_PASSWORD

Authentication Failure Response

{
  "user_info": {
    "auth": 0
  }
}

Base URL

http://SERVER_ADDRESS:PORT/player_api.php

Replace SERVER_ADDRESS and PORT with your server details.

User Info

Get account information and server details.

Request

Endpoint: GET /player_api.php

Parameters:

Parameter Type Required Description
username string ✅ Yes Account username
password string ✅ Yes Account password

Note: Do not include an action parameter to get user info.

Example Request

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123"

Example Response

{
  "user_info": {
    "username": "john",
    "password": "secret123",
    "auth": 1,
    "message": "",
    "status": "Active",
    "exp_date": 1735689600,
    "is_trial": 0,
    "active_cons": 1,
    "created_at": 1704067200,
    "max_connections": 2,
    "allowed_output_formats": ["m3u8", "ts"]
  },
  "server_info": {
    "url": "example.com",
    "port": "8080",
    "server_protocol": "http",
    "timezone": "UTC",
    "timestamp_now": 1703980800,
    "time_now": "2024-12-31 12:00:00",
    "rtmp_port": "",
    "https_port": ""
  }
}

User Status Values

Status Description
Active Account is enabled and not expired
Banned Account banned by administrator
Disabled Account is disabled
Expired Account has passed expiration date

Response Fields

user_info Object

Field Type Description
username string Account username
password string Account password
auth integer Authentication status (1 = success, 0 = failed)
message string System message (if any)
status string Account status
exp_date integer/null Expiration timestamp (null = never expires)
is_trial integer Trial account flag (1 = trial, 0 = regular)
active_cons integer Current active connections
created_at integer Account creation timestamp
max_connections integer Maximum allowed simultaneous connections
allowed_output_formats array Allowed streaming formats

server_info Object

Field Type Description
url string Server URL or IP address
port string Server port
server_protocol string Protocol (http/https)
timezone string Server timezone
timestamp_now integer Current server timestamp
time_now string Current server time (Y-m-d H:i:s)
rtmp_port string RTMP port (if available)
https_port string HTTPS port (if available)

Live Channels

Get Live Categories

Retrieve all available live stream categories.

Request

Endpoint: GET /player_api.php

Parameters:

Parameter Type Required Description
username string ✅ Yes Account username
password string ✅ Yes Account password
action string ✅ Yes get_live_categories

Example Request

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_live_categories"

Example Response

[
  {
    "category_id": "1",
    "category_name": "Sports",
    "parent_id": 0
  },
  {
    "category_id": "2",
    "category_name": "News",
    "parent_id": 0
  },
  {
    "category_id": "3",
    "category_name": "Entertainment",
    "parent_id": 0
  }
]

Response Fields

Field Type Description
category_id string Unique category identifier
category_name string Category display name
parent_id integer Parent category ID (0 = root)

Get Live Streams

Retrieve all available live channels, optionally filtered by category.

Request

Endpoint: GET /player_api.php

Parameters:

Parameter Type Required Description
username string ✅ Yes Account username
password string ✅ Yes Account password
action string ✅ Yes get_live_streams
category_id string ❌ No Filter by category ID

Example Request - All Streams

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_live_streams"

Example Request - Filter by Category

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_live_streams&category_id=1"

Example Response

[
  {
    "num": 1,
    "name": "Sports Channel HD",
    "stream_type": "live",
    "stream_id": 101,
    "stream_icon": "http://example.com/icons/sports.png",
    "epg_channel_id": "sports.us",
    "added": "1704067200",
    "category_id": "1",
    "tv_archive": 0,
    "direct_source": "",
    "tv_archive_duration": 0
  },
  {
    "num": 2,
    "name": "News 24/7",
    "stream_type": "live",
    "stream_id": 102,
    "stream_icon": "http://example.com/icons/news.png",
    "epg_channel_id": "news.us",
    "added": "1704067200",
    "category_id": "2",
    "tv_archive": 0,
    "direct_source": "",
    "tv_archive_duration": 0
  }
]

Response Fields

Field Type Description
num integer Stream number in list
name string Channel display name
stream_type string Always live for live streams
stream_id integer Unique stream identifier
stream_icon string Channel logo URL
epg_channel_id string EPG channel identifier
added string Timestamp when stream was added
category_id string Category the stream belongs to
tv_archive integer TV archive availability (0/1)
direct_source string Direct source URL (if available)
tv_archive_duration integer Archive duration in days

Playing a Live Stream

To play a live stream, use this URL format:

http://SERVER:PORT/USERNAME/PASSWORD/STREAM_ID.EXT

Example:

http://example.com:8080/john/secret123/101.m3u8
http://example.com:8080/john/secret123/101.ts

VOD (Movies)

Get VOD Categories

Retrieve all available movie categories.

Request

Endpoint: GET /player_api.php

Parameters:

Parameter Type Required Description
username string ✅ Yes Account username
password string ✅ Yes Account password
action string ✅ Yes get_vod_categories

Example Request

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_vod_categories"

Example Response

[
  {
    "category_id": "10",
    "category_name": "Action",
    "parent_id": 0
  },
  {
    "category_id": "11",
    "category_name": "Comedy",
    "parent_id": 0
  },
  {
    "category_id": "12",
    "category_name": "Drama",
    "parent_id": 0
  }
]

Get VOD Streams

Retrieve all available movies, optionally filtered by category.

Request

Endpoint: GET /player_api.php

Parameters:

Parameter Type Required Description
username string ✅ Yes Account username
password string ✅ Yes Account password
action string ✅ Yes get_vod_streams
category_id string ❌ No Filter by category ID

Example Request - All Movies

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_vod_streams"

Example Request - Filter by Category

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_vod_streams&category_id=10"

Example Response

[
  {
    "num": 1,
    "name": "Action Movie 2024",
    "stream_type": "movie",
    "stream_id": 5001,
    "stream_icon": "http://example.com/posters/movie1.jpg",
    "added": "1704067200",
    "category_id": "10",
    "direct_source": "",
    "rating": 7.5,
    "rating_5based": 4,
    "custom_sid": null,
    "container_extension": "mkv"
  },
  {
    "num": 2,
    "name": "Comedy Film",
    "stream_type": "movie",
    "stream_id": 5002,
    "stream_icon": "http://example.com/posters/movie2.jpg",
    "added": "1704153600",
    "category_id": "11",
    "direct_source": "",
    "rating": 6.8,
    "rating_5based": 3,
    "custom_sid": null,
    "container_extension": "mp4"
  }
]

Response Fields

Field Type Description
num integer Movie number in list
name string Movie title
stream_type string Always movie for VOD
stream_id integer Unique movie identifier
stream_icon string Movie poster URL
added string Timestamp when movie was added
category_id string Category the movie belongs to
direct_source string Direct source URL (if available)
rating float/null Rating out of 10
rating_5based integer Rating out of 5 (rounded up)
custom_sid null Custom stream ID
container_extension string File extension (mp4, mkv, avi, etc.)

Get VOD Info

Retrieve detailed information about a specific movie.

Request

Endpoint: GET /player_api.php

Parameters:

Parameter Type Required Description
username string ✅ Yes Account username
password string ✅ Yes Account password
action string ✅ Yes get_vod_info
vod_id integer ✅ Yes Movie/VOD stream ID

Example Request

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_vod_info&vod_id=5001"

Example Response

{
  "info": {
    "imdb_id": "",
    "movie_image": "http://example.com/posters/movie1.jpg",
    "genre": "Action, Thriller",
    "plot": "An exciting action movie about a hero saving the world.",
    "cast": "Actor One, Actor Two, Actor Three",
    "director": "Famous Director",
    "rating": 7.5,
    "releasedate": "2024-01-15",
    "duration_secs": 7200,
    "duration": "02:00:00",
    "bitrate": 4500,
    "kinopoisk_url": "",
    "episode_run_time": "",
    "youtube_trailer": "",
    "actors": "Actor One, Actor Two, Actor Three",
    "name": "Action Movie 2024",
    "name_o": "Action Movie 2024",
    "cover_big": "http://example.com/posters/movie1.jpg",
    "description": "An exciting action movie about a hero saving the world.",
    "age": "",
    "rating_mpaa": "",
    "rating_count_kinopoisk": 0,
    "country": "",
    "backdrop_path": [],
    "audio": [],
    "video": []
  },
  "movie_data": {
    "stream_id": 5001,
    "name": "Action Movie 2024",
    "added": "1704067200",
    "category_id": "10",
    "container_extension": "mkv",
    "custom_sid": "",
    "direct_source": ""
  }
}

Response Fields

info Object
Field Type Description
imdb_id string IMDB identifier
movie_image string Movie poster URL
genre string Movie genres
plot string Movie plot/synopsis
cast string Cast members
director string Director name
rating float/null Rating out of 10
releasedate string Release date
duration_secs integer Duration in seconds
duration string Duration formatted (HH:MM:SS)
bitrate integer Video bitrate
youtube_trailer string YouTube trailer URL
name string Movie title
description string Movie description
backdrop_path array Backdrop images
audio array Audio track information
video array Video track information
movie_data Object
Field Type Description
stream_id integer Stream identifier
name string Movie title
added string Timestamp when added
category_id string Category ID
container_extension string File extension
custom_sid string Custom stream ID
direct_source string Direct source URL

Playing a VOD Stream

To play a movie, use this URL format:

http://SERVER:PORT/movie/USERNAME/PASSWORD/STREAM_ID.EXTENSION

Example:

http://example.com:8080/movie/john/secret123/5001.mkv

Series

⚠️ Note: Series endpoints are not available in this API version. The available actions are limited to:

  • get_live_categories
  • get_vod_categories
  • get_live_streams
  • get_vod_streams
  • get_vod_info
  • get_short_epg
  • get_simple_data_table

Series functionality may be available in other API endpoints or a different version.

EPG (Electronic Program Guide)

Get Short EPG

Retrieve a short EPG listing for a specific channel.

Request

Endpoint: GET /player_api.php

Parameters:

Parameter Type Required Description
username string ✅ Yes Account username
password string ✅ Yes Account password
action string ✅ Yes get_short_epg
stream_id integer ✅ Yes Live stream ID
limit integer ❌ No Number of EPG entries (default: 4)

Example Request - Default Limit

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_short_epg&stream_id=101"

Example Request - Custom Limit

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_short_epg&stream_id=101&limit=10"

Example Response

{
  "epg_listings": [
    {
      "id": "12345",
      "epg_id": "67890",
      "title": "TW9ybmluZyBOZXdz",
      "description": "RGFpbHkgbmV3cyBicm9hZGNhc3Q=",
      "start": "2024-12-31 08:00:00",
      "end": "2024-12-31 09:00:00",
      "start_timestamp": 1704009600,
      "stop_timestamp": 1704013200
    },
    {
      "id": "12346",
      "epg_id": "67890",
      "title": "U3BvcnRzIFVwZGF0ZQ==",
      "description": "TGF0ZXN0IHNwb3J0cyBoaWdobGlnaHRz",
      "start": "2024-12-31 09:00:00",
      "end": "2024-12-31 10:00:00",
      "start_timestamp": 1704013200,
      "stop_timestamp": 1704016800
    }
  ]
}

Response Fields

Field Type Description
id string EPG entry ID
epg_id string EPG channel ID
title string Program title (Base64 encoded)
description string Program description (Base64 encoded)
start string Start time (Y-m-d H:i:s)
end string End time (Y-m-d H:i:s)
start_timestamp integer Start time as Unix timestamp
stop_timestamp integer End time as Unix timestamp

Important: The title and description fields are Base64 encoded. Decode them to get the actual text.

Decoding Example (JavaScript)

const title = atob("TW9ybmluZyBOZXdz"); // "Morning News"
const description = atob("RGFpbHkgbmV3cyBicm9hZGNhc3Q="); // "Daily news broadcast"

Decoding Example (Python)

import base64
title = base64.b64decode("TW9ybmluZyBOZXdz").decode('utf-8')  # "Morning News"

Decoding Example (PHP)

$title = base64_decode("TW9ybmluZyBOZXdz"); // "Morning News"

Get Full EPG

Retrieve a complete EPG listing for a specific channel (up to 1000 entries).

Request

Endpoint: GET /player_api.php

Parameters:

Parameter Type Required Description
username string ✅ Yes Account username
password string ✅ Yes Account password
action string ✅ Yes get_simple_data_table
stream_id integer ✅ Yes Live stream ID

Example Request

curl -X GET "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_simple_data_table&stream_id=101"

Example Response

{
  "epg_listings": [
    {
      "id": "12345",
      "epg_id": "67890",
      "title": "TW9ybmluZyBOZXdz",
      "description": "RGFpbHkgbmV3cyBicm9hZGNhc3Q=",
      "start": "2024-12-31 08:00:00",
      "end": "2024-12-31 09:00:00",
      "start_timestamp": 1704009600,
      "stop_timestamp": 1704013200,
      "now_playing": 1,
      "has_archive": 0
    },
    {
      "id": "12346",
      "epg_id": "67890",
      "title": "U3BvcnRzIFVwZGF0ZQ==",
      "description": "TGF0ZXN0IHNwb3J0cyBoaWdobGlnaHRz",
      "start": "2024-12-31 09:00:00",
      "end": "2024-12-31 10:00:00",
      "start_timestamp": 1704013200,
      "stop_timestamp": 1704016800,
      "now_playing": 0,
      "has_archive": 0
    }
  ]
}

Additional Response Fields

Field Type Description
now_playing integer Currently playing indicator (1 = yes, 0 = no)
has_archive integer Archive availability (1 = yes, 0 = no)

Note: The first entry in the response has now_playing: 1 to indicate it's the current program.

Response Codes

HTTP Status Codes

Code Description
200 Success
400 Bad Request
401 Unauthorized (invalid credentials)
500 Server Error

Authentication Response

auth Value Description
1 Authentication successful
0 Authentication failed

Data Models

User Object

{
  "username": "string",
  "password": "string",
  "auth": "integer",
  "message": "string",
  "status": "string (Active|Banned|Disabled|Expired)",
  "exp_date": "integer|null",
  "is_trial": "integer",
  "active_cons": "integer",
  "created_at": "integer",
  "max_connections": "integer",
  "allowed_output_formats": ["string"]
}

Category Object

{
  "category_id": "string",
  "category_name": "string",
  "parent_id": "integer"
}

Live Stream Object

{
  "num": "integer",
  "name": "string",
  "stream_type": "live",
  "stream_id": "integer",
  "stream_icon": "string",
  "epg_channel_id": "string",
  "added": "string",
  "category_id": "string",
  "tv_archive": "integer",
  "direct_source": "string",
  "tv_archive_duration": "integer"
}

VOD Stream Object

{
  "num": "integer",
  "name": "string",
  "stream_type": "movie",
  "stream_id": "integer",
  "stream_icon": "string",
  "added": "string",
  "category_id": "string",
  "direct_source": "string",
  "rating": "float|null",
  "rating_5based": "integer",
  "custom_sid": "null",
  "container_extension": "string"
}

EPG Entry Object

{
  "id": "string",
  "epg_id": "string",
  "title": "string (Base64)",
  "description": "string (Base64)",
  "start": "string (Y-m-d H:i:s)",
  "end": "string (Y-m-d H:i:s)",
  "start_timestamp": "integer",
  "stop_timestamp": "integer",
  "now_playing": "integer (only in get_simple_data_table)",
  "has_archive": "integer (only in get_simple_data_table)"
}

Stream URL Formats

Live Stream URL

http://SERVER:PORT/USERNAME/PASSWORD/STREAM_ID.EXTENSION

Extensions: m3u8, ts

Example:

http://example.com:8080/john/secret123/101.m3u8

VOD/Movie URL

http://SERVER:PORT/movie/USERNAME/PASSWORD/STREAM_ID.EXTENSION

Extensions: mp4, mkv, avi (as specified in container_extension)

Example:

http://example.com:8080/movie/john/secret123/5001.mkv

Series Episode URL

http://SERVER:PORT/series/USERNAME/PASSWORD/STREAM_ID.EXTENSION

Quick Reference

Complete API Endpoints Summary

Endpoint Method Action Required Params Optional Params
/player_api.php GET User Info username, password -
/player_api.php GET get_live_categories username, password -
/player_api.php GET get_live_streams username, password category_id
/player_api.php GET get_vod_categories username, password -
/player_api.php GET get_vod_streams username, password category_id
/player_api.php GET get_vod_info username, password, vod_id -
/player_api.php GET get_short_epg username, password, stream_id limit
/player_api.php GET get_simple_data_table username, password, stream_id -

Example Workflow

1. Authenticate and Get User Info

curl "http://example.com:8080/player_api.php?username=john&password=secret123"

2. Get Live Categories

curl "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_live_categories"

3. Get Streams in a Category

curl "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_live_streams&category_id=1"

4. Get EPG for a Stream

curl "http://example.com:8080/player_api.php?username=john&password=secret123&action=get_short_epg&stream_id=101"

5. Play the Stream

http://example.com:8080/john/secret123/101.m3u8

Documentation generated based on Xtream Codes Player API source code.

Reference in New Issue View Git Blame Copy Permalink