微矩阵使用指南

API 使用指南

使用 Bearer Token 调用微矩阵 Open API，读取公众号、上传图片素材、创建微信草稿、查询流量主数据，并了解正式发布接口的认证边界。

由微矩阵文档团队维护 · 最后更新：2026 年 8 月 20 日

API 概述

微矩阵提供 RESTful Open API，可从 CI/CD、自动化脚本、CMS 或 AI Agent 读取公众号信息、上传图片素材、创建微信草稿和查询流量主数据。所有公开接口都使用 Bearer Token 认证；默认 Token 只开放草稿与读取能力，不开放直接发布。

API 基本信息

基础路径：/api/open/*

数据格式：JSON（请求和响应）

认证方式：Bearer Token（HTTP Header）

响应格式：{ success: boolean, data?: any, message?: string }

管理 Token 交互式文档

认证方式

所有 Open API 请求都需要在 HTTP Header 中携带 Bearer Token：

Authorization: Bearer mp_your_token_here

如果 Token 无效或已过期，API 将返回 401 状态码：

{
  "success": false,
  "code": "TOKEN_NOT_FOUND",
  "message": "Token 不存在或已被删除"
}

接口列表

以下是 Open API 提供的所有接口：

方法	路径	说明
`GET`	/api/open/agent/context	获取 Agent 接入上下文、权限 scope、能力边界和发布策略
`GET`	/api/open/accounts	获取已授权的公众号列表
`GET`	/api/open/account-style	获取账号样式配置（可选 ?appid=xxx）
`GET`	/api/open/publisher/summary	获取流量主累计概览，支持多公众号合计
`GET`	/api/open/publisher/settlement-summary	获取指定时间段收益汇总，支持按公众号或总计
`GET`	/api/open/publisher/settlement-daily	获取指定时间段每日收益趋势，支持按公众号或总计
`POST`	/api/open/draft	从 Markdown 创建微信草稿并同步后台文章
`POST`	/api/open/materials/image	从图片 URL 上传微信图片素材，返回封面 mediaId 或正文图片 url
`POST`	/api/open/publish	提交微信发布任务；需要 publish:write 且公众号已微信认证
`GET`	/api/open/publish/status	通过 publishId 查询微信异步发布任务结果
`POST`	/api/mcp	远程 HTTP MCP JSON-RPC 工具入口，支持 tools/list 和 tools/call

提示：访问「API 文档」页面可以查看完整的交互式文档，包括请求参数、响应示例和在线调试功能。

POST /api/open/draft 请求体

{
  "article_type": "news 或 newspic",
  "title": "文章标题（必填）",
  "content": "Markdown 内容（必填）",
  "appid": "目标公众号 appid（多账号时建议必填）",
  "author": "作者名",
  "summary": "摘要（最多 120 字）",
  "coverImageUrl": "封面图 URL",
  "imageUrls": ["仅 newspic 使用，可选"],
  "imageMediaIds": ["仅 newspic 使用，可选"],
  "coverInfo": { "...仅 newspic 使用..." },
  "productInfo": { "...仅 newspic 使用..." },
  "sourceUrl": "原文链接",
  "showCoverPic": true,
  "openComment": true,
  "fansOnlyComment": false,
  "themeConfig": { "...样式配置..." }
}

默认 article_type 为news。当传newspic时，至少提供一项图片来源：imageUrls、imageMediaIds或 coverImageUrl。

接口成功后会同时返回微信草稿 mediaId 和系统本地文章articleId。返回的文章会直接出现在后台「文章管理」中，后续应先人工检查，再在微信公众平台或具备权限的发布接口中提交发布。

流量主收益查询示例

# 1) 查累计概览
GET /api/open/publisher/summary?appids=wx123,wx456

# 2) 查区间汇总
GET /api/open/publisher/settlement-summary?appids=wx123,wx456&startDate=2026-01-01&endDate=2026-04-14&groupBy=appid

# 3) 查区间总趋势
GET /api/open/publisher/settlement-daily?appids=wx123,wx456&startDate=2026-01-01&endDate=2026-04-14&groupBy=total

图片素材上传

微信文章图片有两种上传路径，不能混用：封面图和图片消息需要永久图片素材mediaId；正文插图需要图文内图片url。微矩阵的草稿接口会自动处理正文图片和封面；如果你需要提前复用素材，可以单独调用图片上传接口。

POST /api/open/materials/image
Authorization: Bearer mp_your_token_here
Content-Type: application/json

{
  "appid": "wx1234567890abcdef",
  "imageUrl": "https://example.com/cover.jpg",
  "usage": "cover"
}

usage=cover会调用微信永久素材接口，返回 mediaId，可用于coverMediaId或图片消息的 imageMediaIds。usage=content会调用图文内图片接口，返回可放入正文 HTML 的微信图片 URL。

图片 URL 必须可由服务器公网访问。平台会做 SSRF 防护、下载超时和大小限制；如果图片带防盗链、需要登录或超过限制，上传会失败。

提交发布任务

正式发布使用微信 freepublish/submit能力。根据微信官方发布能力页面，2025 年 7 月起个人主体账号、企业主体未认证账号及不支持认证的账号会被回收发布接口调用权限。因此微矩阵默认不把publish:write放进普通 API Token。

POST /api/open/publish
Authorization: Bearer mp_token_with_publish_write
Content-Type: application/json

{
  "articleId": "cm9abc123def456ghi789jkl",
  "confirmPublish": true
}

# 或者直接传微信草稿 mediaId
{
  "appid": "wx1234567890abcdef",
  "mediaId": "MEDIA_ID_xxxx",
  "confirmPublish": true
}

成功响应只代表“已提交微信发布任务”，会返回publishId。你还需要调用状态查询接口确认最终结果：

GET /api/open/publish/status?appid=wx1234567890abcdef&publishId=PUBLISH_ID
Authorization: Bearer mp_token_with_publish_write

对普通用户和 Agent，建议流程仍然停在“创建微信草稿”。如果公众号未认证、Token 没有发布权限，或微信审核未通过，用户必须去微信公众平台草稿箱或微矩阵后台进行人工检查和发布。

MCP 工具入口

远程 HTTP MCP 使用 JSON-RPC 请求。未带 Token 时可以初始化和读取工具列表；真正调用工具时必须在 Header 中携带 API Token。

POST /api/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

POST /api/mcp
Authorization: Bearer mp_your_token_here
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "wematrix_create_draft",
    "arguments": {
      "appid": "wx1234567890abcdef",
      "title": "每日简报",
      "content": "# 标题\n\n这是正文"
    }
  }
}

当前 MCP 工具覆盖 Agent Context、账号列表、账号样式、草稿创建、图片素材上传、流量主收益、提交发布任务和发布状态查询。发布相关工具需要publish:write权限，并且不会改变人工审核边界。

Agent 与 CLI

如果你是给 Codex、Claude、Cursor、CI 脚本或自定义 Agent 接入微矩阵，推荐优先使用wematrix-cli。CLI 已经封装了 Token 读取、JSON 输出、错误结构、MCP 配置和草稿创建命令，适合 Agent 稳定调用。

npm install -g wematrix-cli

export WEMATRIX_BASE_URL="https://mp.lingxiaoyao.cn"
export WEMATRIX_TOKEN="mp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

wematrix context
wematrix accounts
wematrix styles --appid wx123
wematrix draft create post.md --title "每日简报" --appid wx123

查看 CLI 与 MCP 指南 npm 包

Agent 接入时不要把真实 Token 放进 prompt、共享 MCP 配置或 Git 仓库。建议使用环境变量、Secret 管理器或平台内置的密钥管理能力。

错误码说明

API 返回的常见错误码及其含义：

HTTP 状态码	错误码	说明
400	`MISSING_PARAM`	缺少必填参数
401	`UNAUTHORIZED`	缺少或未正确填写 Authorization 请求头
401	`TOKEN_NOT_FOUND`	Token 不存在、已删除或需要重新创建
404	`NOT_FOUND`	指定的公众号不存在或未授权
400	`WECHAT_API_ERROR`	微信 API 调用失败
500	`INTERNAL_ERROR`	服务器内部错误

最佳实践

使用 Open API 时的建议和注意事项：

Token 安全

不要将 Token 硬编码在代码中，使用环境变量管理
不要将 Token 提交到 Git 仓库
定期轮换 Token，建议设置合理的过期时间
为不同用途创建独立的 Token，便于权限管理

错误处理

始终检查响应中的 success 字段
根据 code 字段判断具体错误类型
微信 API 可能因为 Token 过期失败，平台会自动刷新后重试
批量操作时对微信 API 错误和临时失败实现退避重试，不要无限循环请求

内容格式

文章内容使用标准 Markdown 语法，平台会自动转换为微信图文格式
封面图建议使用 HTTPS 链接，尺寸推荐 900x383 像素
摘要（summary）最多 120 个字符，超出时接口会返回参数过长错误