CCTV央视节目单获取免费 API 接口完整教程（含 PHP / Python 示例）

apihz

608人浏览 · 2026-07-10 15:19:57

apihz · 2026-07-10 15:19:57 发布

支持 CCTV 全系列频道，可查约前 21 天到未来 7 天的节目单，返回数据里包含节目名、开播/结束时间、时长、栏目主页等完整字段。

下面从接口说明、参数、返回值到 PHP / Python 实战代码，一次性讲透。

一、接口基本信息

项目	说明
接口地址	`https://cn.apihz.cn/api/fun/cctv.php`
请求方式	GET 或 POST 都支持
返回格式	JSON
调用限制	公共 ID/KEY 有每分钟频次限制，建议注册后使用自己的 ID 和 KEY，每日调用无上限
数据范围	约前 21 天到未来 7 天

二、请求参数详解

必填参数

参数	名称	说明
`id`	用户 ID	用户中心的数字 ID，如 `id=10000000`
`key`	通讯秘钥	用户中心通讯秘钥，如 `key=15he5h15ty854j5sr152hs2`

可选参数

参数	名称	默认值	说明
`type`	频道	`1`（CCTV‑1）	1‑17 对应 CCTV‑1~CCTV‑17，101=CCTV‑5+，102=CCTV‑4 欧洲，103=CCTV‑4 美洲
`nian`	年	当前年	如 `nian=2026`
`yue`	月	当前月	如 `yue=07`，建议两位
`ri`	日	当日	如 `ri=10`，日期一般不能超过前 21 天与后 7 天

常用频道 `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一般是参数或秘钥错误。

顶层字段

字段	说明
`code`	200 成功，400 错误
`msg`	提示信息
`channelName`	频道名称，如 `CCTV-1 综合`
`playurl`	官方播放网页（注意是网页，不是直链播放地址）
`vipflag`	VIP 标识，0=免费
`list`	节目列表数组

list 内每个节目字段

字段	说明
`title`	节目名称
`startTime`	开播时间戳
`startTime2`	格式化开播时间
`endTime`	结束时间戳
`endTime2`	格式化结束时间
`showTime`	开播时间（几点几分）
`eventType`/ `eventId`	特殊标记，常用于体育赛事、晚会
`length`	节目时长，单位秒
`column_url`/ `columnBackvideourl`	栏目主页链接
`top`	权重标识

四、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
$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

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 或赛事提醒时可以重点处理这两个字段。