直播 API 接口文档

接口概览

请求方式

GET

无需鉴权参数

响应格式

JSON

UTF-8 编码

流媒体格式

FLV · M3U8

支持双格式播放

数据内容

实时赛事

全球联赛直播流

世界杯相关接口

World Cup leagueId=1000（世界杯小组赛赛程 / 比赛列表）

接口	用途	说明
/live/api?leagueId=1000	世界杯 API 输出	返回结构与 `/live/api` 完全一致；默认返回未来 30 天（用于展示赛程）

        示例 · curl
      
# 世界杯 API（结构同 /live/api）
curl -s 'https://api.okzhibo.live/live/api?leagueId=1000'

响应结构预览

response.json

{

"code": 0,

"message": "成功",

"data": {

"total": 89,

"list": [

{

"matchId": 1693747,

"leagueName": "斯亚乙",

"status": "下半场",

"home": { id, name, logo, score },

"away": { id, name, logo, score },

"live_flv_url": "https://...",

"live_m3u8_url": "https://..."

}

]

}

顶层响应字段

root 根对象字段说明

字段名	类型	说明
code	number	状态码，`0` 表示请求成功
message	string	状态描述信息，成功时返回 `"成功"`
data	object	包含赛事列表的数据对象含 total（总数）与 list（列表数组）
data.total	number	当前返回的赛事总条数
data.list	array	赛事对象数组，每项为一场比赛

赛事对象字段（list 数组项）

list[] 单场赛事字段说明

字段名	类型	说明
matchId	number	赛事唯一标识 ID 示例：1693747
gameType	number	比赛类型编号当前接口数据均为 6（足球）
leagueId	number	联赛唯一 ID
leagueName	string	联赛名称示例："韩K联"、"中冠"
leagueLogo	string	联赛 Logo 图片 URL
matchTime	number	比赛开始时间（Unix 时间戳，秒级）示例：1778515200 → 2026-05-12 00:00
matchTimeText	string	比赛时间可读格式格式：YYYY-MM-DD HH:mm
status	string	比赛当前状态文字见下方状态码对照表
statusId	number	比赛状态编号见下方状态码对照表
home	object	主队信息对象含 id / name / logo / score
away	object	客队信息对象含 id / name / logo / score
live_flv_url	string	FLV 格式直播流地址适用于 PC 端 flv.js 播放器
live_m3u8_url	string	M3U8 格式 HLS 直播流地址适用于移动端及 HLS 播放器

队伍信息对象（home / away）

team home 与 away 字段相同，结构如下

字段名	类型	说明
id	number	球队唯一 ID
name	string	球队名称（中文）
logo	string	球队 Logo 图片 URL 部分球队 logo 可能为空字符串
score	number	当前比分（未开赛时为 0）

比赛状态码对照表

statusId statusId 与 status 对应关系

statusId	status	阶段	说明
0	未开赛	赛前	比赛尚未开始
1	上半场	进行中	比赛上半场进行中，直播流有效
2	中场	进行中	上下半场间隔休息
3	下半场	进行中	比赛下半场进行中，直播流有效
4	加时	进行中	比赛进入加时赛阶段
5	点球	进行中	点球大战决胜
-1	已结束	赛后	比赛正常结束
-14	推迟	异常	比赛被推迟，直播流可能不可用

使用示例

        JavaScript · Fetch API
      
// 获取直播列表
const res = await fetch('https://api.okzhibo.live/live/api');
const { code, data } = await res.json();

if (code === 0) {
  // 筛选直播中的赛事（statusId 1-5）
  const liveMatches = data.list.filter(
    m => m.statusId >= 1 && m.statusId <= 5
  );

  for (const match of liveMatches) {
    console.log(
      `[${match.leagueName}]`,
      match.home.name, 'vs', match.away.name,
      `${match.home.score}-${match.away.score}`
    );

    // 使用 M3U8 流（推荐移动端）
    videoPlayer.load(match.live_m3u8_url);

    // 或使用 FLV 流（PC 端 flv.js）
    // flvPlayer.load(match.live_flv_url);
  }
}

        Python · requests
      
import requests

resp = requests.get('https://api.okzhibo.live/live/api')
data = resp.json()

if data['code'] == 0:
    for match in data['data']['list']:
        # 格式化比分与状态
        print(
            f"{match['leagueName']} | "
            f"{match['home']['name']} "
            f"{match['home']['score']}:{match['away']['score']} "
            f"{match['away']['name']} | {match['status']}"
        )
        # 直播地址
        m3u8 = match['live_m3u8_url']  # HLS 流
        flv  = match['live_flv_url']   # FLV 流

注意事项

logo 字段为空	部分球队 `logo` 可能返回空字符串 `""`，使用时需做非空判断，展示默认占位图
时间戳单位	`matchTime` 为秒级 Unix 时间戳，JS 中转换需 `× 1000`：`new Date(matchTime * 1000)`
直播流可用性	仅 `statusId` 为 1~5（进行中）时直播流有效；`推迟`、`未开赛`或`已结束`时流地址可能无法访问
请求频率	建议轮询间隔不低于 30 秒，避免对服务器造成过大压力
M3U8 vs FLV	移动端优先使用 `live_m3u8_url`（HLS），PC 端可使用 `live_flv_url` 配合 `flv.js` 获得更低延迟

iframe 方式

页面地址	http://www.okzhibo.live/player.html
适用场景	无需对接接口与播放器，直接嵌入到你的网站页面中

打开 iframe 页面

嵌入代码

          HTML
        
<iframe
  src="http://www.okzhibo.live/player.html"
  width="100%"
  height="560"
  frameborder="0"
  allowfullscreen
></iframe>

预览

新窗口打开

自建播放器（静态页面）

下载地址	/player.zip
目录来源	`/player`（包含 `player.html` / `artplayer.js` / `hls.min.js`）
入口页面	/player/player.html
默认接口	`https://api.okzhibo.live/live/api`

下载 player.zip 打开播放器

部署步骤

          使用说明
        
1) 下载 /player.zip 并解压
2) 把解压后的 player 目录上传到你的网站根目录（或任意静态目录）
3) 浏览器访问：/player/player.html
4) 播放器会自动拉取直播列表并支持点击切换比赛

自定义接口地址

方式	编辑 `/player/player.html`，把默认接口替换为你自己的接口地址
替换内容	搜索并替换：`https://api.okzhibo.live/live/api`
示例	例如替换为：`https://你的域名/live/api`

嵌入到页面

          HTML
        
<iframe
  src="/player/player.html"
  width="100%"
  height="560"
  frameborder="0"
  allowfullscreen
></iframe>

预览

新窗口打开

插件方式（MacCMS）

下载地址	/live.zip
说明文档	/live/README.md

下载 live.zip 打开 README.md

安装与配置（README 摘要）

          README.md
        
# live 插件（OK足球直播）

## 功能

- 赛事列表页：`/index.php/live/index.html`
- 赛事详情/播放页：`/index.php/live/detail/id/{matchId}.html`
- 列表支持筛选：
  - 直播中：`?status=onair`
  - 联赛关键字：`?league=英超`
- 服务器端拉取上游接口并缓存，降低请求频率

## 安装

- 将目录放入：`maccms/addons/live/`
- 后台 → 插件管理 → 找到 live → 安装 → 启用

说明：插件通过 `addons/live/application/` 覆盖机制提供前台控制器，安装后会复制到站点的 `/application/`，无需修改系统核心文件。

## 配置

后台 → 插件管理 → live → 配置：

- `api_url`：上游接口地址（默认 `https://api.okzhibo.live/live/api`）
- `cache_ttl`：缓存秒数（默认 `30`）