# 内置 HTTP API

应用图形界面启动后，会自动在本机 **30088** 端口（`BuiltInServerPort`，见 `env/.env`）监听内置 Express 服务。其它程序可通过 HTTP 调用，与 GUI / CLI 共用同一套登录态与 `pushData` 发布记录。

> **与 CLI 的区别**：HTTP API 依赖 GUI 主进程已运行（托盘/窗口在即可）；CLI 可独立启动。单平台请求会等待上传完成或超时；多平台请求与 GUI 批量发布一致，提交到发布队列后立即返回，实际结果写入 `pushData` 发布记录。

**基础地址**：`http://127.0.0.1:30088`

## 路由一览

| 方法 | 路径                   | 说明                                              |
| ---- | ---------------------- | ------------------------------------------------- |
| GET  | `/`                    | 返回 `MatrixMedia API` 欢迎页                     |
| GET  | `/platforms`           | 返回 HTTP 支持的全部视频平台列表（JSON）          |
| GET  | `/creative-statements` | 返回各平台支持的创作声明选项（对齐 GUI 批量设置） |
| POST | `/changeData`          | 读写本地 JSON 数据（账号树、发布历史等）          |
| POST | `/publish`             | 发布视频到单平台或多平台                          |

静态资源：`/public/*` 映射到 `server/public`。

## GET /platforms

查询 `POST /publish` 支持的全部视频平台（与 CLI `cli publish` 一致）。

**响应示例**：

```json
{
  "success": true,
  "platforms": [
    {
      "code": "dy",
      "name": "抖音",
      "aliases": ["douyin", "抖音"],
      "automated": true,
      "note": null,
      "hasConfig": true
    },
    {
      "code": "xhs",
      "name": "小红书",
      "aliases": ["xiaohongshu", "小红书"],
      "automated": true,
      "note": null,
      "hasConfig": true
    },
    {
      "code": "fqsp",
      "name": "番茄视频",
      "aliases": ["fanqie", "fq", "番茄视频"],
      "automated": false,
      "note": "已支持自动发布与审核状态回查",
      "hasConfig": true
    }
  ]
}
```

## 支持的视频平台

`platform` / `platforms` 可使用 **code** 或 **中文名**，以下平台均可通过 HTTP 发布：

| code   | 平台     | 别名                   | 自动化 |
| ------ | -------- | ---------------------- | ------ |
| `dy`   | 抖音     | douyin / 抖音          | 是     |
| `sph`  | 视频号   | 视频号                 | 是     |
| `blbl` | 哔哩哔哩 | bilibili / 哔哩哔哩    | 是     |
| `bjh`  | 百家号   | 百家号                 | 是     |
| `tt`   | 头条     | toutiao / 头条         | 是     |
| `ks`   | 快手     | kuaishou / 快手        | 是     |
| `xhs`  | 小红书   | xiaohongshu / 小红书   | 是     |
| `fqsp` | 番茄视频 | fanqie / fq / 番茄视频 | 可用   |

> 掘金文章请使用 CLI `publish-article`，当前无 HTTP 接口。

## GET /creative-statements

查询各平台支持的创作声明选项，与 GUI「本地视频发布」批量设置创作声明一致。

**响应字段**：

| 字段           | 说明                                               |
| -------------- | -------------------------------------------------- |
| `default`      | 默认值，一般为 `none`                              |
| `batchOptions` | 全局批量下拉全部选项（value + label）              |
| `platforms`    | 按平台 code 列出 `supports` 与该平台可用 `options` |
| `input`        | HTTP `POST /publish` 入参说明                      |

**声明 value 一览**（也可用中文 label 或各平台页面原文案）：

| value                 | 说明       | 备注              |
| --------------------- | ---------- | ----------------- |
| `none`                | 无标注     | 默认              |
| `ai_generated`        | AI 生成    |                   |
| `fiction`             | 虚构演绎   |                   |
| `marketing`           | 营销推广   | 快手/头条不支持   |
| `personal_opinion`    | 个人观点   | 小红书/头条不支持 |
| `repost`              | 转载       |                   |
| `self_made_no_repost` | 自制禁转载 | 仅哔哩哔哩        |

## POST /changeData

读写本地 JSON 数据，GUI 内部也使用此接口。

**请求体（JSON）**：

| 字段       | 说明                                                     |
| ---------- | -------------------------------------------------------- |
| `fileName` | 数据文件名，如 `account`、`pushData`                     |
| `type`     | 操作类型：`add` / `update` / `delete` / `get` / `config` |
| `item`     | 具体数据项，结构随 `fileName` 与 `type` 变化             |

## POST /publish

发布视频到单平台或多平台（本地路径或 `http(s)` 远程 URL）。参数解析与 `cli publish` 共用 `parseMultiPublishRequest`。

视频元数据字段与 GUI / CLI 一致：`title` 为标题，`description` 为简介，`shortTitle` 仅视频号短标题，`tags` 为标签。抖音 / 快手 / 视频号会把简介与标签拼进正文；小红书正文写简介、标签走话题控件；哔哩哔哩简介和标签各自独立填写；头条 / 百家号只写标题。旧字段 `bt2` 仍兼容：视频号当短标题，其他平台当简介。

**请求体（JSON）**：

| 字段                 | 必填   | 说明                                                                                                                                     |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `platform`           | 单平台 | 上表任一平台 code 或中文名，如 `xhs` / `小红书`（与 `platforms` 二选一）                                                                 |
| `platforms`          | 多平台 | 平台数组，可一次包含全部 8 个平台；如 `["dy","xhs","ks"]` 或对象数组 `[{ "platform": "dy", "phone": "138..." }, ...]`                    |
| `file`               | 是     | 本地视频绝对路径，或 `http://` / `https://` 远程视频 URL（会先下载到临时目录，全部平台发布结束后自动删除；定时发布则在到点执行时再下载） |
| `title`              | 是     | 视频标题                                                                                                                                 |
| `description`        | 否     | 视频简介；抖音、快手、视频号会与标签拼接，小红书写入正文，哔哩哔哩写入简介控件                                                           |
| `shortTitle`         | 否     | 视频号短标题，建议 6 ～ 16 字；其他平台忽略                                                                                              |
| `phone`              | 二选一 | 账号手机号（与 GUI 账号树一致）；多平台时可作为默认值，单个平台对象内可覆盖                                                              |
| `partition`          | 二选一 | 完整 session，如 `persist:13800138000抖音`                                                                                               |
| `bt2`                | 否     | 旧兼容字段：视频号作为短标题，其他平台作为简介                                                                                           |
| `tags`               | 否     | 标签，支持空格 / 逗号分隔；HTTP 会按 GUI 批量发布习惯拆分后再按平台补 `#` 或去 `#`                                                       |
| `publishAt`          | 否     | 一次性定时发布，格式 `YYYY-MM-DD HH:mm:ss`（多平台时需全部一致）                                                                         |
| `draft`              | 否     | `true` 时保存到平台草稿箱，不直接发布                                                                                                    |
| `sphProductId`       | 否     | 视频号商品上架快捷字段（商品编号）；仅视频号生效，等价于 `platformOptions.sph.link.type=product` |
| `sphDramaId` | 否 | 视频号小程序短剧挂载快捷字段（**短剧名称**，如 `泳陷错恋`）；仅视频号生效，等价于 `platformOptions.sph.link.type=mini_drama`                                         |
| `sphSeriesId` | 否 | 视频号剧集挂载快捷字段（**剧集名称**，视频号原生剧集）；仅视频号生效，等价于 `platformOptions.sph.link.type=sph_series`                                         |
| `sphLink`            | 否     | 视频号链接对象，如 `{ "type": "product", "value": "商品编号" }`、`{ "type": "mini_drama", "value": "短剧名称" }` 或 `{ "type": "sph_series", "value": "剧集名称" }`；与三个快捷字段同时传时优先快捷字段                           |
| `platformOptions`    | 否     | 平台专属参数容器；视频号商品也可用 `platformOptions.sph.link`，不会应用到其他平台                                                        |
| `creativeStatement`  | 否     | 全局创作声明，等同 GUI「批量设置创作声明」；支持 value、中文 label 或平台页面原文案（如 `内容由AI生成`）                                 |
| `creativeStatements` | 否     | 按平台覆盖声明，key 用 code 或中文名，如 `{ "dy": "ai_generated", "blbl": "fiction" }`；某平台不支持所选值时回退 `none`                  |

**创作声明优先级**（与 GUI 一致）：`platforms[].creativeStatement` > `creativeStatements[平台]` > `creativeStatement`。

视频号已支持「视频标注」创作声明。某平台不支持所选值时回退为 `none`。可用 `GET /creative-statements` 查询各平台可用选项。

**响应体（JSON）**：

| 字段                             | 说明                                                 |
| -------------------------------- | ---------------------------------------------------- |
| `success`                        | 请求是否被接受；多平台表示已成功提交到发布队列       |
| `status`                         | 单平台为最终状态；多平台提交成功为 `submitted`       |
| `exitCode`                       | 单平台同 CLI；多平台提交成功为 `0`                   |
| `message`                        | 结果说明                                             |
| `total` / `succeeded` / `failed` | 多平台提交汇总；最终成功失败以 `pushData` 记录为准   |
| `results`                        | 多平台时各平台提交明细数组（含 `creativeStatement`） |
| `id`                             | 单平台时写入 `pushData` 的记录 id                    |
| `scheduled` / `publishAt`        | 定时发布时返回                                       |

**HTTP 状态码**：

- 参数错误：HTTP `400`
- 单平台发布失败（如未登录）：HTTP `200`，但 `success: false`、`exitCode: 3`
- 视频号链接添加失败但草稿保存成功：HTTP `200`，`success: false`、`status: needs_attention`、`exitCode: 4`
- 多平台：HTTP 只表示任务是否提交成功，最终结果请查询发布记录
- 服务已配置 CORS，浏览器或本机脚本均可调用

## 示例

单平台发布：

```bash
curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "dy",
    "phone": "13800138000",
    "file": "/Users/me/video.mp4",
    "title": "我的视频标题",
    "tags": "减脂 健身"
  }'
```

视频号商品上架并保存草稿（推荐快捷字段）：

```bash
curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "sph",
    "phone": "13800138000",
    "file": "/Users/me/video.mp4",
    "title": "视频标题",
    "description": "视频简介",
    "shortTitle": "视频号短标题",
    "draft": true,
    "sphProductId": "10000591263144",
    "creativeStatement": "含AI生成内容"
  }'
```

也可用完整对象（视频号商品 / 小程序短剧 / 剧集）：

```json
{
  "platformOptions": {
    "sph": { "link": { "type": "product", "value": "10000591263144" } }
  }
}
```

```json
{
  "platformOptions": {
    "sph": { "link": { "type": "mini_drama", "value": "泳陷错恋" } }
  }
}
```

```json
{
  "platformOptions": {
    "sph": { "link": { "type": "sph_series", "value": "儿媳给我办寿宴" } }
  }
}
```

`sphProductId` / `sphDramaId` / `sphSeriesId` / `sphLink` / `platformOptions.sph` 只会被视频号任务读取。多平台发布时其他平台会忽略它们；不同视频号账号可在各个 `platforms[]` 对象内分别覆盖商品 / 短剧 / 剧集名称。短剧或剧集添加失败时同样走「转存草稿」兜底：HTTP `200`、`status: needs_attention`、`exitCode: 4`。

远程视频 URL：

```bash
curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "dy",
    "phone": "13800138000",
    "file": "https://example.com/video.mp4",
    "title": "我的视频标题"
  }'
```

多平台一次发布（含按平台创作声明，对齐 GUI 批量设置）：

```bash
curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "file": "/Users/me/video.mp4",
    "title": "我的视频标题",
    "creativeStatement": "ai_generated",
    "creativeStatements": {
      "blbl": "fiction",
      "xhs": "marketing"
    },
    "platforms": ["dy", "blbl", "xhs", "ks"]
  }'
```

多平台一次发布（`platforms` 字符串数组）：

```bash
curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "file": "https://example.com/video.mp4",
    "title": "我的视频标题",
    "description": "记录第一次完成五公里的真实体验",
    "shortTitle": "5公里新手挑战",
    "tags": "跑步 新手",
    "platforms": ["dy", "sph", "blbl", "bjh", "tt", "ks", "xhs"]
  }'
```

多平台一次发布（`platforms` 对象数组，各平台可覆盖 `phone`）：

```bash
curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "file": "/Users/me/video.mp4",
    "title": "我的视频标题",
    "tags": "日常 vlog",
    "platforms": [
      { "platform": "dy", "phone": "13800138000" },
      { "platform": "sph", "phone": "13800138000" },
      { "platform": "ks", "phone": "13900139000" }
    ]
  }'
```

多平台响应示例：

```json
{
  "success": true,
  "exitCode": 0,
  "status": "submitted",
  "message": "已提交 3 个平台发布",
  "total": 3,
  "succeeded": 0,
  "failed": 0,
  "results": [
    {
      "platform": "抖音",
      "success": true,
      "exitCode": 0,
      "status": "submitted",
      "message": "已提交发布任务"
    },
    {
      "platform": "视频号",
      "success": true,
      "exitCode": 0,
      "status": "submitted",
      "message": "已提交发布任务"
    },
    {
      "platform": "快手",
      "success": true,
      "exitCode": 0,
      "status": "submitted",
      "message": "已提交发布任务"
    }
  ]
}
```

## 数据统计接口（Stats API）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/stats?phone=<分组>&pt=<平台>` | 读本地快照中的账号粉丝数据 |
| POST | `/stats/sync` | 主动采集：`{"phone":"123","pt":"blbl"}` |
| GET | `/stats/work?phone=<分组>&pt=<平台>&title=<标题>` | 按完整标题查视频发布数据 |

- 平台支持短码（`dy` `sph` `blbl` `bjh` `tt` `ks` `xhs`）或中文名
- 与 `/changeData` 相同守卫：需 `X-Matrix-Token` 头或 localhost/file Origin
- `POST /stats/sync` 复用 GUI 登录态采集，返回 `overview`（fans/plays/likes/comments/shares/favorites）与 `workCount`

示例：

```bash
curl -H "Origin: http://localhost:30088" "http://localhost:30088/stats?phone=123&pt=blbl"
curl -X POST -H "Content-Type: application/json" -H "Origin: http://localhost:30088" \
  -d '{"phone":"123","pt":"sph"}' http://localhost:30088/stats/sync
```