> 来源：https://mac-cms.com/cms/cms-api
> 简介：MacCMS V10（苹果CMS）标准 JSON API 接口说明，含视频列表、详情、搜索、分类接口与 from 播放源筛选、返回字段，适用于空壳影视等影视 App 对接。
> 更新：2026-11-02

# MacCMS API接口说明

MacCMS V10 提供标准的JSON格式API接口，可用于空壳影视等影视APP对接。

## 接口地址格式

```
https://你的域名/api.php/provide/vod/
```

::: tip 提示
接口类型需选择 **MacCMS V10** 或 **苹果V10**，一般资源站首页默认提供此格式。
:::

## 两套 API 别搞混：Provide vs Vod

MacCMS V10 的 `api` 模块下其实有**两套**面向不同场景的接口，返回结构完全不同，对接前先认准用哪套：

| 接口 | 典型地址 | 用途 | 返回结构 |
|------|----------|------|----------|
| **Provide**（资源站/采集提供接口） | `/api.php/provide/vod/` | 资源站对外输出、站点间互采、对接空壳影视 | `{ code, msg, page, list, (class) }` |
| **Vod**（自研 REST 接口） | `/api.php/vod/get_list`、`/api.php/vod/get_detail` 等 | MacCMS 官方自家 App 的前端接口 | `{ code:1, msg, info:{...} }` |

::: warning 对接空壳影视请用 Provide
**对接空壳影视、资源站互采，用的都是 `Provide`（`/api.php/provide/vod/`）这套**，本文下面讲的 `ac` / `from` / 返回字段都是针对它。

`/api.php/vod/get_*`（如 `get_list`、`get_detail`、`get_hot`、`get_class`…）是 MacCMS 另外一套自研 REST 接口，面向它自家 App，返回的是 `{code,msg,info}` 结构，字段和 Provide 完全不一样，**不要拿错接口**。
:::

## 基础参数说明（Provide 接口）

| 参数 | 说明 | 示例 |
|------|------|------|
| ac | 动作类型，有效值 `list` / `videolist` / `detail`（见下方「ac 取值」） | ac=detail |
| t | 分类ID（受资源站 typefilter 限制） | t=1 |
| pg | 页码 | pg=1 |
| pagesize | 每页条数，上限 100 | pagesize=20 |
| h | 最近更新小时数 | h=24 |
| ids | 指定视频ID（可多个用逗号隔开） | ids=123 |
| wd | 搜索关键词（按 `vod_name` 模糊匹配） | wd=电影名 |
| year | 年份，4 位或 `起-止` 区间 | year=2024 |
| from | 播放源筛选（见下方「播放源筛选」） | from=ffm3u8 |
| at | 输出格式，`at=xml` 返回 XML（默认 JSON） | at=xml |

### ac 取值

`ac` 只有三个有效值，决定返回哪些字段：

| ac | 含义 | 返回字段 |
|------|------|----------|
| `list`（或不传 ac） | 分类列表 + 影片基础列表 | 精简字段，含 `vod_play_from`，**不含 `vod_play_url`**；额外返回 `class` 分类数组 |
| `videolist` | 影片列表（全字段） | `*` 全字段，**含 `vod_play_url`** 等播放地址 |
| `detail` | 影片详情（全字段） | 同 `videolist`，配合 `ids` 时按资源站配置给影片 `vod_hits+1` |

源码里的判断是 `if ($this->_param['ac'] == 'videolist' || $this->_param['ac'] == 'detail') { $field = '*'; }`——也就是只有 `videolist` 和 `detail` 才会把字段放到全量、带出播放地址；`detail` 与 `videolist` 的差异主要在 `detail` 配合 `ids` 会累加播放量。

## 常用接口

### 获取视频列表

```
/api.php/provide/vod/?ac=videolist&t=1&pg=1
```

返回该分类下的视频列表，支持分页。

### 获取视频详情

```
/api.php/provide/vod/?ac=detail&ids=123
```

返回指定ID的视频详情，包含 `vod_play_from`（播放源标识）与 `vod_play_url`（播放地址）。

不带 `ids` 直接访问 `接口地址?ac=detail`（即 `/api.php/provide/vod/?ac=detail`），返回的是含 `vod_play_from` / `vod_play_url` 的详情列表，是确认一个资源站播放源标识最直接的办法。

### 搜索视频

```
/api.php/provide/vod/?ac=videolist&wd=关键词
```

根据关键词搜索视频。

### 获取分类列表

```
/api.php/provide/vod/?ac=list
```

返回所有视频分类信息。

## 播放源筛选

可通过 `from` 参数指定播放源，减少返回数据量。路径式和查询式两种写法**等价**：

```
路径式：/api.php/provide/vod/from/ffm3u8/
查询式：/api.php/provide/vod/?from=ffm3u8
```

源码里 `from` 本质是个查询参数：`?from=xxx`（值长度 ≥ 2 个字符）生效；路径式 `/from/ffm3u8/` 由 ThinkPHP5 的 pathinfo 解析成同样的 `from=ffm3u8`，所以两种写法效果一样，文档里的路径式示例照用即可。

其中 `ffm3u8` 为播放源名称。访问 `接口地址?ac=detail` 即可在返回 JSON 的 `vod_play_from` 字段看到该站的播放源名（多个用逗号分隔，挑 m3u8 类的）。怎么找资源站、怎么验证接口可用，见[影视采集资源怎么找](/cms/cms-share)。

## 返回字段说明

::: tip 字段随 ac 变化
下面是 `ac=videolist` / `ac=detail` 的返回示例（全字段，含 `vod_play_url`）。注意 **`ac=list` 时 `list` 元素是精简字段**：只有 `vod_id` / `vod_name` / `type_id` / `type_name` / `vod_en` / `vod_time` / `vod_remarks` / `vod_play_from`，**没有 `vod_play_url`**，并且顶层会多一个 `class` 分类数组（`[{type_id,type_pid,type_name}]`）。要拿播放地址必须用 `videolist` 或 `detail`。
:::

```json
{
  "code": 1,
  "msg": "数据列表",
  "page": 1,
  "pagecount": 100,
  "limit": "20",
  "total": 2000,
  "list": [
    {
      "vod_id": 1,
      "vod_name": "视频名称",
      "vod_pic": "封面图地址",
      "vod_year": "2024",
      "vod_area": "大陆",
      "vod_remarks": "更新至10集",
      "vod_play_from": "ffm3u8",
      "vod_play_url": "第1集$url#第2集$url"
    }
  ]
}
```

`ac=list` 时返回形如：

```json
{
  "code": 1,
  "msg": "数据列表",
  "page": 1,
  "pagecount": 100,
  "limit": "20",
  "total": 2000,
  "class": [
    { "type_id": 1, "type_pid": 0, "type_name": "电影" }
  ],
  "list": [
    {
      "vod_id": 1,
      "vod_name": "视频名称",
      "type_id": 1,
      "type_name": "电影",
      "vod_en": "shipin",
      "vod_time": "2024-01-01 12:00:00",
      "vod_remarks": "更新至10集",
      "vod_play_from": "ffm3u8"
    }
  ]
}
```