MatrixMedia HTTP 发布接口：让 AI 工作流直接驱动多平台视频发布

引言：CLI 不够用的场景

MatrixMedia 从一开始就提供了 CLI 命令行接口，可以用 Shell 脚本批量发布视频到抖音、B站、快手等平台。但随着 AI 自动化工具的普及，越来越多的开发者在用 n8n、Dify、Zapier 或者纯 Python 脚本来编排内容生产流水线------这类工具调用外部服务的方式几乎清一色是 HTTP 请求，而不是执行本地命令。

命令行调用有几个固有的限制：

n8n、Dify 等低代码平台的节点本质上是 HTTP 客户端，没有"执行本机 Shell"的通用能力
跨语言集成时，调用子进程的方式在 Windows 和 macOS 上行为不一致
AI Agent 工具调用（Tool Use / Function Calling）的标准载体也是 HTTP

新版 MatrixMedia 在 GUI 主进程中内置了一个轻量 Express 服务，监听 127.0.0.1:30088，对外暴露 /publish 等几个 REST 接口。只要 GUI 在运行，任何能发 HTTP 请求的程序都可以驱动多平台发布，不需要操心 CLI 路径、进程权限或跨平台兼容问题。

架构说明

MatrixMedia 的架构是 Electron + Puppeteer。GUI 主进程负责管理各平台的浏览器会话（登录态保存在 Electron 的 session partition 里），CLI 工具通过读取同一份本地数据来复用这些会话。

新增的 HTTP 服务就内嵌在 GUI 主进程里，和 CLI 共享同一套登录态，所以：

不需要额外的认证 Token------服务只监听 127.0.0.1，本机调用即可
账号管理依然在 GUI 界面里完成，HTTP 接口用手机号来指定要使用哪个账号
发布记录统一落在 GUI 的历史面板中，方便人工复查

整体数据流如下：

bash 复制代码

AI 工作流 / Python 脚本 / n8n
        │  HTTP POST /publish
        ▼
 MatrixMedia GUI（127.0.0.1:30088）
        │  Puppeteer 操作浏览器
        ▼
 各平台上传页面（抖音 / B站 / 快手 ...）

服务在 GUI 启动时自动开启，关闭 GUI 后服务随之停止。

核心接口

可用路由

方法	路径	说明
GET	/platforms	返回支持的平台列表及平台代码
GET	/creative-statements	返回各平台可用的创作声明选项
POST	/changeData	读写本地 JSON 数据
POST	/publish	发布视频（核心接口）

支持的平台代码：dy（抖音）、sph（视频号）、blbl（哔哩哔哩）、bjh（百家号）、tt（头条）、ks（快手）、xhs（小红书）。

先用 /platforms 确认当前版本支持哪些平台：

bash 复制代码

curl http://127.0.0.1:30088/platforms

POST /publish 参数说明

参数	类型	必填	说明
platform	string	二选一	单平台代码，如 `dy`
platforms	array	二选一	多平台数组，如 `["dy","blbl","ks"]`
file	string	是	本地绝对路径或 `https://` 远程 URL
title	string	是	视频标题
phone	string	是	账号手机号，与 GUI 账号树一致
tags	string	否	标签，空格或逗号分隔
bt2	string	否	视频号短标（仅 sph 平台使用）
publishAt	string	否	定时发布，格式 `YYYY-MM-DD HH:mm:ss`
creativeStatement	string	否	全局创作声明，如 `ai_generated` / `fiction` / `marketing`
creativeStatements	object	否	按平台覆盖声明，如 `{"dy":"ai_generated","blbl":"fiction"}`

用法示例

1. 单平台发布

最简单的场景：把一个本地视频发布到抖音。

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": "减脂 健身"
  }'

单平台请求会等待上传完成后再返回最终状态，适合同步等待结果的场景。

2. 多平台一键分发

把同一个视频同时投递到抖音、B站、小红书、快手四个平台：

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": "我的视频标题",
    "platforms": ["dy", "blbl", "xhs", "ks"]
  }'

多平台模式下，任务提交到内部队列后立即返回，响应示例：

json 复制代码

{
  "success": true,
  "exitCode": 0,
  "status": "submitted",
  "message": "已提交 4 个平台发布",
  "total": 4,
  "results": [...]
}

各平台实际发布进度可在 GUI 历史面板中查看，或通过 /changeData 接口轮询发布记录。

3. 远程视频 URL

如果视频文件存储在云端（比如 AI 生成后上传到 OSS 或 S3），可以直接把下载链接填入 file 字段，MatrixMedia 会先把文件下载到本地临时目录，发布完成后自动清理：

bash 复制代码

curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "file": "https://your-oss.example.com/output/video-20260625.mp4",
    "title": "AI 生成的科普视频",
    "platforms": ["dy", "blbl", "xhs"]
  }'

这个特性对 AI 工作流特别有用------视频生成节点产出的是一个 URL，下一个节点直接把 URL 传给 MatrixMedia，整个流程不需要在本机做任何文件落盘操作。

4. 定时发布

工作流在凌晨批量生成视频，但希望在早上 8 点发布，可以用 publishAt 参数：

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": "早安健身计划",
    "platform": "dy",
    "publishAt": "2026-06-26 08:00:00"
  }'

5. 创作声明

各平台对 AI 生成内容有合规要求，creativeStatement 字段统一设置所有平台的声明，也可以用 creativeStatements 按平台分别指定：

bash 复制代码

curl -X POST http://127.0.0.1:30088/publish \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "file": "/Users/me/ai-video.mp4",
    "title": "AI 制作的城市风景",
    "platforms": ["dy", "blbl", "xhs"],
    "creativeStatement": "ai_generated",
    "creativeStatements": {
      "blbl": "fiction"
    }
  }'

creativeStatements 里指定的平台会覆盖 creativeStatement 的全局值。可用的声明类型通过 GET /creative-statements 查询获得，不同版本可能有差异，建议动态获取。

接入 AI 工作流

有了 HTTP 接口，接入各类自动化平台的思路就很清晰了。

n8n

在 n8n 工作流里，加一个 HTTP Request 节点，方法选 POST，URL 填 http://127.0.0.1:30088/publish，Body 类型选 JSON，把前面节点产出的视频路径或 URL、标题、标签等字段映射过来就行。因为 n8n 本身运行在本机，直接访问 127.0.0.1 没有跨机器的问题。

典型的工作流结构可以是：触发器（定时 / Webhook）→ 获取视频 URL（HTTP Request）→ 调用 MatrixMedia 发布（HTTP Request）→ 发送通知（Telegram / 飞书）。

Python 脚本

用 requests 库两行代码就能完成调用，适合嵌入到已有的内容生产脚本中：

python 复制代码

import requests

resp = requests.post(
    "http://127.0.0.1:30088/publish",
    json={
        "phone": "13800138000",
        "file": "https://your-oss.example.com/video.mp4",
        "title": "Python 自动发布测试",
        "platforms": ["dy", "blbl", "ks"],
        "tags": "Python 自动化",
        "creativeStatement": "ai_generated",
    }
)
print(resp.json())

可以把这段逻辑封装成函数，作为内容管道的最后一步------视频生成完成后直接调用，无需人工介入。

Dify 工作流

Dify 的工作流支持 HTTP 请求节点，可以把 LLM 生成的视频标题、标签等字段通过变量注入到请求体中。整体思路是：LLM 节点生成标题和标签 → 代码节点组装请求体 → HTTP 节点调用 /publish → 结束节点记录结果。Dify 的变量系统让你很方便地把 AI 生成的内容直接传递给发布接口，不需要写额外的中间件。

AI Agent Tool Call

如果你在构建一个自主 Agent（比如用 LangChain、AutoGen 或者原生 Function Calling），可以把 /publish 封装成一个 Tool，让 Agent 在内容生成完毕后自主决定发布到哪些平台。接口的 JSON 结构天然适合作为工具参数 schema，定义一次就能复用。

注意事项

HTTP 服务监听 127.0.0.1，不会暴露到局域网或外网，本身是安全的，但要确保调用方和 GUI 在同一台机器上运行
使用前需要在 GUI 中完成账号登录，HTTP 接口本身不处理登录流程
多平台模式返回 submitted 后，实际发布是异步进行的，如需确认结果请在 GUI 历史面板中查看
publishAt 是平台侧的定时发布，不是本地延迟调用，视频会先上传到平台，再在指定时间发布

小结

MatrixMedia 的 HTTP 接口做的事情不复杂：把原来只有命令行才能触发的多平台发布能力，变成了一个任何 HTTP 客户端都能调用的本地服务。对于已经在用 n8n、Dify 编排 AI 内容流水线的开发者来说，接入成本几乎是零------加一个 HTTP Request 节点，填好参数，就把"视频分发到多平台"这个环节自动化掉了。

随着 AI 视频生成工具（文生视频、数字人等）的成熟，内容生产的瓶颈正在从"生成"转向"分发运营"。一个能被程序驱动的发布接口，是让 AI 内容工作流真正闭环的关键一环。

项目开源，欢迎 Star 和贡献：

github.com/hanliang97/...