MatrixMedia 矩媒 HTTP API 实战:一条 curl 命令触发多平台视频批量发布

原创2026-10-21 23:16:231,874 阅读

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 首次打开会提示「来自身份不明的开发者」,在 系统设置 → 隐私与安全性 中点击 仍要打开 即可:

矩媒 MatrixMedia HTTP API 环境准备: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 兜底)。

MatrixMedia 矩媒 HTTP API 排错:访问未知路由时返回 404 错误

  • HTTP 200 但 success: false:这是正常现象,业务失败(未登录、上传中断)通过 success / exitCode 字段表达,脚本里判断时请检查 JSON 而不是只看状态码。
  • 端口被占用:服务启动时若遇到 EADDRINUSE 会自动间隔 1.5s 重试最多 5 次(index.js),重启矩媒一般即可恢复。

📌 相关资料

一条 curl 命令把「打开界面 → 选平台 → 选视频 → 点发布」压缩成一行文本,矩媒 HTTP API 让视频矩阵分发第一次变得可编程。

登录后查看全文
MatrixMedia