支持 CCTV 全系列频道,可查约前 21 天到未来 7 天的节目单,返回数据里包含节目名、开播/结束时间、时长、栏目主页等完整字段。
下面从接口说明、参数、返回值到 PHP / Python 实战代码,一次性讲透。
一、接口基本信息
项目 |
说明 |
接口地址 |
|
请求方式 |
GET 或 POST 都支持 |
返回格式 |
JSON |
调用限制 |
公共 ID/KEY 有每分钟频次限制,建议注册后使用自己的 ID 和 KEY,每日调用无上限 |
数据范围 |
约前 21 天到未来 7 天 |
二、请求参数详解
必填参数
参数 |
名称 |
说明 |
|
用户 ID |
用户中心的数字 ID,如 |
|
通讯秘钥 |
用户中心通讯秘钥,如 |
可选参数
参数 |
名称 |
默认值 |
说明 |
|
频道 |
|
1‑17 对应 CCTV‑1~CCTV‑17,101=CCTV‑5+,102=CCTV‑4 欧洲,103=CCTV‑4 美洲 |
|
年 |
当前年 |
如 |
|
月 |
当前月 |
如 |
|
日 |
当日 |
如 |
常用频道 type对照表
type |
频道 |
type |
频道 |
1 |
CCTV‑1 综合 |
9 |
CCTV‑9 纪录 |
2 |
CCTV‑2 财经 |
10 |
CCTV‑10 科教 |
3 |
CCTV‑3 综艺 |
13 |
CCTV‑13 新闻 |
4 |
CCTV‑4 亚洲 |
14 |
CCTV‑14 少儿 |
5 |
CCTV‑5 体育 |
16 |
CCTV‑16 奥林匹克 |
6 |
CCTV‑6 电影 |
17 |
CCTV‑17 农业农村 |
7 |
CCTV‑7 国防军事 |
101 |
CCTV‑5+ 体育赛事 |
8 |
CCTV‑8 电视剧 |
102/103 |
CCTV‑4 欧洲/美洲 |
三、返回参数详解
接口统一用 code判断状态:200成功,400一般是参数或秘钥错误。
顶层字段
字段 |
说明 |
|
200 成功,400 错误 |
|
提示信息 |
|
频道名称,如 |
|
官方播放网页(注意是网页,不是直链播放地址) |
|
VIP 标识,0=免费 |
|
节目列表数组 |
list 内每个节目字段
字段 |
说明 |
|
节目名称 |
|
开播时间戳 |
|
格式化开播时间 |
|
结束时间戳 |
|
格式化结束时间 |
|
开播时间(几点几分) |
|
特殊标记,常用于体育赛事、晚会 |
|
节目时长,单位秒 |
|
栏目主页链接 |
|
权重标识 |
四、GET 请求示例
直接在浏览器或 curl 里就能调:
https://接口盒子/api/fun/cctv.php?id=你的ID&key=你的KEY&type=1&nian=2026&yue=07&ri=10
成功时返回结构类似:
{ "code": 200, "channelName": "CCTV-1 综合", "playurl": "https://tv.cctv.com/live/cctv1", "vipflag": 0, "list": [ { "title": "新闻联播", "startTime": 1780865580, "startTime2": "2026-06-08 04:53:00", "endTime": 1780867620, "endTime2": "2026-06-08 05:27:00", "showTime": "04:53", "length": 2040, "column_url": "https://tv.cctv.com/lm/xwlb/index.shtml" } ] }
失败时:
{"code":400,"msg":"通讯秘钥错误。"}
五、PHP 调用示例
下面给你 GET 和 POST 两种写法,实际项目里推荐 POST,参数不容易被日志记下来。
示例 1:PHP GET 请求(cURL)
<?php $apiUrl = 'https://接口盒子/api/fun/cctv.php'; // 替换为你的 ID 和 KEY $id = '你的ID'; $key = '你的KEY'; $type = 1; // CCTV-1 $nian = 2026; $yue = 7; $ri = 10; $url = sprintf( '%s?id=%s&key=%s&type=%d&nian=%d&yue=%02d&ri=%02d', $apiUrl, $id, $key, $type, $nian, $yue, $ri ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 10); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 本地测试可关,生产环境建议开启 $response = curl_exec($ch); if (curl_errno($ch)) { echo '请求错误:' . curl_error($ch); exit; } curl_close($ch); $data = json_decode($response, true); if ($data['code'] == 200) { echo "频道:{$data['channelName']}\n"; echo "播放页:{$data['playurl']}\n\n"; foreach ($data['list'] as $item) { echo "[{$item['showTime']}] {$item['title']} 时长:" . gmdate('i分s秒', $item['length']) . "\n"; } } else { echo "接口返回错误:{$data['msg']}\n"; }
示例 2:PHP POST 请求(推荐)
php
php
<?php $apiUrl = 'https://接口盒子/api/fun/cctv.php'; $params = [ 'id' => '你的ID', 'key' => '你的KEY', 'type' => 5, // CCTV-5 体育 'nian'=> 2026, 'yue' => 7, 'ri' => 10, ]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $apiUrl); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 10); $response = curl_exec($ch); curl_close($ch); $data = json_decode($response, true); header('Content-Type:text/html; charset=utf-8'); if ($data['code'] == 200) { echo '<h2>' . $data['channelName'] . '</h2>'; echo '<ul>'; foreach ($data['list'] as $item) { echo '<li>' . $item['startTime2'] . ' <b>' . $item['title'] . '</b>' . ' (' . floor($item['length'] / 60) . '分钟)' . '</li>'; } echo '</ul>'; } else { echo '错误:' . $data['msg']; }
六、Python 调用示例
Python 这边同样给 GET 和 POST,顺手封装了一个把秒数转成「分:秒」的小函数,实战里很常用。
示例 1:Python GET 请求
import requests API_URL = "https://接口盒子/api/fun/cctv.php" params = { "id": "你的ID", "key": "你的KEY", "type": 1, # CCTV-1 "nian": 2026, "yue": 7, "ri": 10, } def sec_to_min_sec(seconds: int) -> str: """把秒数转成 分:秒""" m, s = divmod(seconds, 60) return f"{m}分{s}秒" resp = requests.get(API_URL, params=params, timeout=10) resp.encoding = "utf-8" data = resp.json() if data.get("code") == 200: print(f"频道:{data['channelName']}") print(f"播放页:{data['playurl']}") print("-" * 40) for item in data["list"]: print( f"[{item['showTime']}] {item['title']} " f"({sec_to_min_sec(item['length'])})" ) # 如果有栏目主页,也打出来 if item.get("column_url"): print(f" 栏目主页:{item['column_url']}") else: print(f"接口错误:{data.get('msg')}")
示例 2:Python POST 请求 + 按节目名过滤
这个例子更贴近真实需求——比如你只想查「新闻联播」什么时候播:
python
python
import requests API_URL = "https://接口盒子/api/fun/cctv.php" data = { "id": "你的ID", "key": "你的KEY", "type": 1, # CCTV-1 "nian": 2026, "yue": 7, "ri": 10, } resp = requests.post(API_URL, data=data, timeout=10) resp.encoding = "utf-8" result = resp.json() if result.get("code") != 200: print(f"请求失败:{result.get('msg')}") exit() print(f"频道:{result['channelName']}") # 只打印「新闻联播」 for item in result["list"]: if "新闻联播" in item["title"]: print( f"\n📺 找到《新闻联播》:" f"{item['startTime2']} ~ {item['endTime2']}," f"时长 {item['length']} 秒" ) if item.get("column_url"): print(f"栏目主页:{item['column_url']}") # 也可以把所有节目按时间排序后输出 print("\n--- 全天节目 ---") for item in result["list"]: print(f"{item['showTime']} {item['title']}")
七、几个容易踩的坑
- playurl 不是播放直链
它返回的是 CCTV 官方播放网页,不是.m3u8直链,别拿它直接当视频源塞进播放器。 - 日期范围有限制
一般只能查前 21 天到未来 7 天,超出会返回异常或空数据。 - length 单位是秒
返回里length: 2040表示 2040 秒,也就是 34 分钟,用之前记得换算。 - eventType 可用来做特殊标记
体育赛事、晚会等可能会有eventType和eventId,做 EPG 或赛事提醒时可以重点处理这两个字段。
八、适合拿它做什么
- IPTV / EPG 系统:定时拉取节目单,生成 XMLTV 格式供播放器读取
- 节目提醒机器人:比如每天自动推送「新闻联播马上开始」
- 影视资讯站:展示 CCTV 各频道今日节目
- 录制排程:配合
startTime时间戳做定时录制