API说明文档

返回上一级 · 返回目录

用途：服务健康检查。该接口不读取解析数据，适合作为监控探活。

鉴权	不需要
参数	无

请求示例

curl "https://wxmp.aicloud.xx.kg/api/health"

返回结构

{
  "status": "ok",
  "service": "wxmpapi",
  "time": "2026-07-10T10:00:00+08:00",
  "version": "0.1.0",
  "environment": "prod"
}

返回上一级 · 返回目录

用途：解析公开微信公众号文章或合集链接，返回固定、扁平、便于上层工具消费的 JSON。

参数	位置	必填	说明
url	query	是	公众号文章或合集 URL，例如 https://mp.weixin.qq.com/s/...

行为：不鉴权；文章返回 text 和图片/音频/视频 metadata URL；合集只返回文章 URL 列表，不逐篇解析正文；不下载资产；不保存 artifact；不返回 raw HTML。

请求示例

curl -G "https://wxmp.aicloud.xx.kg/api/v1/resolve"   --data-urlencode "url=https://mp.weixin.qq.com/s/xxxx"

返回结构：文章

{
  "status": "success",
  "type": "article",
  "mp_name": "...",
  "author": "...",
  "publish_time": "...",
  "title": "...",
  "text": "正文...",
  "image": [{"url": "https://mmbiz.qpic.cn/...", "index": 1}],
  "audio": [{"url": "https://res.wx.qq.com/voice/getvoice?mediaid=...", "name": "...", "duration_ms": 226000}],
  "video": [{"url": "https://mp.weixin.qq.com/mp/videoplayer?...", "vid": "wxv_...", "cover_url": "..."}]
}

返回结构：合集

{
  "status": "success",
  "type": "album",
  "mp_name": null,
  "title": "合集标题",
  "article_count": 92,
  "articles": [
    {"title": "...", "url": "https://mp.weixin.qq.com/s?...", "publish_time": "...", "digest": "...", "cover_url": "..."}
  ]
}

返回上一级 · 返回目录

用途：管理解析入口。用于获取 raw HTML、保存文章 metadata/raw_content_html/content_text/media URL metadata，或在本地环境下载图片/音频等内部场景。

Header	必填	说明
X-Wxmpapi-Management-Key	是	管理密钥，只应放在服务端或可信脚本中。

字段	说明
url	公众号文章或合集 URL
return.format	metadata / text / html_raw
assets.mode	none / metadata_only / download
storage.save	是否保存文章解析结果；配置 Supabase 时写入 Postgres，否则保存本地 artifact
album.max_articles	合集最多解析篇数，默认 5

请求示例：获取 raw HTML

curl -X POST "https://wxmp.aicloud.xx.kg/api/v1/management/links/resolve"   -H "Content-Type: application/json"   -H "X-Wxmpapi-Management-Key: <secret>"   -d '{
    "url": "https://mp.weixin.qq.com/s/xxxx",
    "return": {"format": "html_raw", "content": true},
    "storage": {"save": false},
    "assets": {"mode": "none"}
  }'

请求示例：保存 artifact

curl -X POST "https://wxmp.aicloud.xx.kg/api/v1/management/links/resolve"   -H "Content-Type: application/json"   -H "X-Wxmpapi-Management-Key: <secret>"   -d '{
    "url": "https://mp.weixin.qq.com/s/xxxx",
    "return": {"format": "html_raw", "content": true},
    "storage": {"save": true}
  }'

返回结构

{
  "status": "success",
  "request_id": "req_xxx",
  "result_type": "article",
  "source": "direct_mobile_wechat",
  "article": {
    "title": "...",
    "content": {
      "format": "html_raw",
      "text": null,
      "html_raw": "<div id="js_content">...</div>",
      "html_length": 1234
    },
    "assets": {"mode": "none | metadata_only | download", "images": [], "audio": [], "video": []},
    "artifact": {
      "artifact_id": "art_xxx",
      "storage": "local",
      "local_dir": "...",
      "files": {"metadata": {"path": "metadata.json"}, "content_text": {"path": "content-text.txt"}, "raw_html": {"path": "raw-content.html"}}
    }
  },
  "account": {"subscribed": false},
  "actions": {"article_saved": true, "account_subscribed": false}
}

返回上一级 · 返回目录

用途：解析单篇文章并生成短期 ZIP。创建导出需要管理密钥；返回的下载链接使用高熵 token，默认 5 分钟有效，下载时不需要管理密钥。

Header	必填	说明
X-Wxmpapi-Management-Key	是	创建导出时需要。下载 URL 本身不需要该 header。

字段	说明
url	单篇公众号文章 URL
storage.save	是否同时保存文章解析结果到 Supabase Postgres；默认 false
export.format	P0 仅支持 zip
export.media_mode	P0 仅支持 url_only，HTML 引用原始微信媒体 URL，不下载媒体
export.save_export	P0 仅支持 false，不上传 Supabase Storage
export.ttl_seconds	临时下载有效期，默认 300 秒

请求示例

curl -X POST "https://wxmp.aicloud.xx.kg/api/v1/management/exports/article"   -H "Content-Type: application/json"   -H "X-Wxmpapi-Management-Key: <secret>"   -d '{
    "url": "https://mp.weixin.qq.com/s/xxxx",
    "storage": {"save": false},
    "export": {"format": "zip", "media_mode": "url_only", "save_export": false, "ttl_seconds": 300}
  }'

返回结构

{
  "status": "success",
  "request_id": "req_xxx",
  "export": {
    "export_id": "exp_xxx",
    "format": "zip",
    "media_mode": "url_only",
    "save_export": false,
    "expires_in": 300,
    "expires_at": "2026-07-10T17:31:26+08:00",
    "download_url": "https://wxmp.aicloud.xx.kg/api/v1/exports/exp_xxx/download?token=...",
    "file_size": 29207,
    "title": "...",
    "mp_name": "..."
  }
}

ZIP 暂存 /tmp/wxmpapi_exports；免费 Render 环境下不保证跨重启/重新部署可用。ZIP 结构为 article/article.html、article/content-text.txt、article/metadata.json、article/assets.json。

返回上一级 · 返回目录

用途：下载管理导出接口生成的临时 ZIP。该接口不需要管理密钥，但必须携带创建接口返回的 token。

参数	位置	必填	说明
export_id	path	是	创建导出时返回的导出 ID
token	query	是	高熵下载 token

请求示例

curl -L "https://wxmp.aicloud.xx.kg/api/v1/exports/exp_xxx/download?token=..." -o article.zip

错误 token 或不存在返回 404；过期或临时文件已消失返回 410。

返回上一级 · 返回目录

用途：验证管理密钥是否可用。

Header	必填	说明
X-Wxmpapi-Management-Key	是	管理密钥

请求示例

curl "https://wxmp.aicloud.xx.kg/api/v1/management/status"   -H "X-Wxmpapi-Management-Key: <secret>"

返回结构

{
  "status": "ok",
  "service": "wxmpapi",
  "environment": "prod"
}

无 key 或 key 错误时返回 HTTP 401。