MatrixMedia 矩媒 HTTP API 实战:一条 curl 命令触发多平台视频批量发布
MatrixMedia 矩媒 HTTP API 实战:一条 curl 命令触发多平台视频批量发布
MatrixMedia(矩媒)是一款开源的自媒体矩阵发布工具,内置 HTTP API:只要 GUI 在运行,一条 curl 命令即可把同一视频批量发布到抖音、视频号、小红书等 8 大平台,与界面操作共用同一套登录态和发布记录,特别适合脚本、定时任务和 AI 智能体自动编排。
🔌 什么是矩媒 HTTP API?
打开矩媒图形界面后,应用会在本机 30088 端口自动启动一个内置 Express 服务,基础地址为 http://127.0.0.1:30088。服务只绑定回环地址(见 src/main/server/index.js),不会向局域网暴露,可以安全地在办公网络里开着。
与 CLI 的区别只有一点:
| 方式 | 前置条件 | 行为 |
|---|---|---|
| CLI | 可独立启动 | 同步等待任务完成 |
| HTTP API | GUI 主进程需在运行(窗口或托盘在即可) | 单平台同步等待;多平台进队列后立即返回 |
路由一览(完整说明见 docs/http-api.md):
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | / |
返回 MatrixMedia API 欢迎页 |
| GET | /platforms |
查询支持的 8 个视频平台列表 |
| GET | /creative-statements |
查询各平台创作声明选项 |
| POST | /changeData |
读写本地 JSON 数据(账号树、发布历史等) |
| POST | /publish |
发布视频到单平台或多平台(本文主角) |
📦 环境准备:3 步启动内置服务
第 1 步:安装并打开矩媒 GUI。 从发布渠道下载安装包后直接启动;macOS 首次打开会提示「来自身份不明的开发者」,在 系统设置 → 隐私与安全性 中点击 仍要打开 即可:
第 2 步:登录至少一个平台账号。 在 GUI 里扫码登录,记录账号树的手机号(后面 curl 要用到)。CLI 与 GUI 共用 persist:<手机号><平台> session,登录一次即可反复调用。
第 3 步:验证服务已就绪。 浏览器访问 http://127.0.0.1:30088,看到 MatrixMedia API 欢迎页,或执行:
curl http://127.0.0.1:30088/platforms
返回 {"success": true, "platforms": [...]} 即表示内置服务可用。
🚀 实战一:一条 curl 命令发布到单平台
POST /publish 的最小请求体只需 4 个字段:
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": "减脂 健身"
}'
| 字段 | 说明 |
|---|---|
platform |
平台 code 或中文名:dy / xhs / sph / blbl / bjh / tt / ks / fqsp |
phone |
账号手机号(与 GUI 账号树一致) |
file |
本地视频绝对路径,或 http(s):// 远程 URL(自动下载、发完清理) |
title |
视频标题(必填) |
tags |
标签,空格或逗号分隔,按平台习惯自动补 # |
单平台请求会同步等待上传完成再返回,响应里的 success: true + exitCode: 0 即代表发布成功,id 是写入本地 pushData 发布记录的编号,可在 GUI 发布历史中查到。
🚀 实战二:一条 curl 命令批量发布多平台
把 platform 换成 platforms 数组(二者不可同时传),即可一次分发到全部 8 个平台:
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": "记录第一次完成五公里的真实体验",
"tags": "跑步 新手",
"platforms": ["dy", "sph", "blbl", "bjh", "tt", "ks", "xhs"]
}'
platforms 还支持对象数组写法,让不同平台用不同账号(见 parsePublishArgs.js 与 publishVideo.js 的解析逻辑):
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" }
]
}'
多平台请求与 GUI 批量发布完全一致:提交到发布队列后立即返回,远程视频只下载一次,各平台顺序执行:
{
"success": true,
"exitCode": 0,
"status": "submitted",
"message": "已提交 3 个平台发布",
"total": 3,
"results": [
{ "platform": "抖音", "status": "submitted", "message": "已提交发布任务" },
{ "platform": "视频号", "status": "submitted", "message": "已提交发布任务" },
{ "platform": "快手", "status": "submitted", "message": "已提交发布任务" }
]
}
多平台响应里的
submitted只表示「任务已进队列」,最终成功/失败以pushData发布记录为准,在 GUI 发布历史页即可逐条核对。
⚙️ 高级参数速查表
| 参数 | 用途 |
|---|---|
description |
视频简介;抖音/快手/视频号会与标签拼进正文,小红书写入正文,哔哩哔哩写入简介控件 |
shortTitle |
视频号短标题(建议 6~16 字),其他平台忽略 |
publishAt |
定时发布,格式 YYYY-MM-DD HH:mm:ss(多平台时需全部一致) |
draft |
设为 true 时只保存到平台草稿箱,不直接发布 |
creativeStatement |
全局创作声明,如 ai_generated;与 GUI「批量设置创作声明」一致 |
creativeStatements |
按平台覆盖,如 { "blbl": "fiction", "xhs": "marketing" } |
sphProductId / sphDramaId / sphSeriesId |
视频号商品编号 / 短剧名称 / 剧集名称快捷挂载字段 |
定时 + 草稿箱的组合是测试发布流程的好办法:
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": "定时草稿测试",
"publishAt": "2026-10-22 09:00:00",
"draft": true
}'
📖 读懂响应:status 与 exitCode 对照表
| 场景 | HTTP 状态 | 关键字段 | 含义 |
|---|---|---|---|
| 参数错误 | 400 |
success: false |
缺必填字段、平台不认识等 |
| 单平台成功 | 200 |
success: true、exitCode: 0 |
发布完成,id 对应发布记录 |
| 单平台业务失败(如未登录) | 200 |
success: false、exitCode: 3 |
请求本身合法,去 GUI 检查登录态 |
| 视频号链接挂载失败但草稿已保存 | 200 |
status: needs_attention、exitCode: 4 |
转存草稿兜底,需人工关注 |
| 多平台提交成功 | 200 |
status: submitted |
任务已进队列,结果看发布记录 |
🛠️ 常见问题排查清单
Connection refused/ 无法连接:矩媒 GUI 没有启动。HTTP API 依赖 GUI 主进程在运行,窗口最小化到托盘即可。/changeData、/stats返回 403:这两个接口带请求守卫(requestGuard.js),需要X-Matrix-Token头或来自localhost/127.0.0.1的 Origin。/publish不受此限制,本机脚本可放心调用。- 返回
{"error": 404}:写错了路径,服务对未知路由统一返回 404(server.js 兜底)。
- HTTP 200 但
success: false:这是正常现象,业务失败(未登录、上传中断)通过success/exitCode字段表达,脚本里判断时请检查 JSON 而不是只看状态码。 - 端口被占用:服务启动时若遇到
EADDRINUSE会自动间隔 1.5s 重试最多 5 次(index.js),重启矩媒一般即可恢复。
📌 相关资料
- 官方接口文档:docs/http-api.md
- 路由与发布逻辑源码:src/main/server/routes/index.js
- 多平台发布队列:src/main/services/publishVideo.js
- 请求守卫与安全说明:src/main/server/requestGuard.js
- 服务端口绑定与 CORS 配置:src/main/server/server.js
一条 curl 命令把「打开界面 → 选平台 → 选视频 → 点发布」压缩成一行文本,矩媒 HTTP API 让视频矩阵分发第一次变得可编程。

