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	查询参数	是	公众号文章或合集链接，例如 https://mp.weixin.qq.com/s/...

行为：不鉴权；文章返回正文文本和图片、音频、视频链接；合集只返回文章链接列表，不逐篇解析正文；不下载媒体文件；不持久保存解析结果；不返回原始 HTML。

文章链接无需手动补充 chksm，正文抓取会自动处理；不依赖微信读书登录态。

失败或部分解析时附 diagnostics：reason_code 区分作者隐私（CONTENT_PRIVATE）、平台限制（CONTENT_BLOCKED）、发布者删除（CONTENT_DELETED）、验证页和未知缺正文；message / suggestion 提供中文说明与建议。原因不明仍为 NO_JS_CONTENT，提示不改变重试策略。

请求示例

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": "..."}
  ]
}

解析提示见 article.diagnostics；保存提示见 storage_error.diagnostics，均含安全原因及中文 message / suggestion，无需开启 raw_meta。

保存失败返回409（身份冲突）、502（存储错误）或503（存储不可用），响应保留解析结果，并通过storage_error和actions.article_saved=false说明保存状态。

返回上一级 · 返回目录

用途：管理解析入口。用于获取原始 HTML、保存文章元数据、正文与媒体链接，或在本地环境下载图片和音频。

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

字段	说明
url	公众号文章或合集链接
return.format	metadata 元数据 / text 正文文本 / html_raw 原始 HTML
assets.mode	none 不处理 / metadata_only 仅媒体链接 / download 下载
storage.save	是否保存单篇文章解析结果；配置 Supabase 时写入 Postgres，否则保存本地产物。合集逐篇入库尚未实现；解析合集时使用 storage.save=false，或明确选择 storage.backend=local 保存本地产物
album.max_articles	合集最多解析篇数，默认 5

请求示例：获取原始 HTML

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

请求示例：保存解析结果

curl -X POST "https://wxmp.aicloud.xx.kg/api/v1/management/links/resolve"   -H "Content-Type: application/json"   -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY"   -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。创建导出需要管理密钥；返回的下载链接使用临时下载令牌，默认 5 分钟有效，下载时不需要管理密钥。

请求头	必填	说明
X-Wxmpapi-Management-Key	是	创建导出时需要。下载链接本身不需要该请求头。

字段	说明
url	单篇公众号文章链接
storage.save	是否同时保存文章解析结果到 Supabase Postgres；默认 false
export.format	当前仅支持 zip
export.media_mode	当前仅支持 url_only，HTML 引用原始微信媒体链接，不下载媒体
export.save_export	当前仅支持 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: $WXMPAPI_MANAGEMENT_API_KEY"   -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	路径参数	是	创建导出时返回的导出 ID
token	查询参数	是	临时下载令牌

请求示例

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

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

返回上一级 · 返回目录

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

请求头	必填	说明
X-Wxmpapi-Management-Key	是	管理密钥

请求示例

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

返回结构

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

密钥缺失或错误时返回 HTTP 401。

查询文章列表

返回上一级 · 返回目录

用途：按公众号和发布时间查询文章，查看正文是否已保存。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	可选筛选：book_id 与 account_id 不能同时传入；limit 默认20、最多100；cursor 用于翻页。

请求示例

curl "https://wxmp.aicloud.xx.kg/api/v1/management/articles?book_id=MP_WXS_2398482821&limit=20" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY"

返回说明

items 返回文章信息，next_cursor 用于下一页，翻页时保留筛选条件。 book_id 为微信读书公众号标识，返回该号的采集记录，含尚未保存正文的文章； 不传时查询正式文章库，可用内容库的数字编号 account_id 筛选，两种标识不能混用。

published_from（含）和 published_before（不含）限定发布时间，均为 Unix 秒。 body_status=available 表示已有可读正文，not_saved 表示尚未保存。 暂停、取消订阅及账号离线不妨碍读取已有内容。

读取已保存正文

返回上一级 · 返回目录

用途：按内容库文章编号读取正文和媒体信息。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	路径中的 article_id 为数据库数字编号；include_html 默认 false；assets_after_id 为媒体分页游标。

请求示例

curl "https://wxmp.aicloud.xx.kg/api/v1/management/articles/123?include_html=true" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY"

返回说明

默认返回已保存的正文文本；include_html=true 附带原始 HTML。 媒体每页最多100项，用 assets_next_after_id 作为下一次 assets_after_id。 尚无正文时返回 body_status=not_saved、content=null，不会自动解析原文。

按采集标识读取正文

返回上一级 · 返回目录

用途：用公众号标识与文章标识查询正文及最近处理结果。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	book_id、review_id 必填，文章标识保留原值（包括 ~）；可用 include_html 和 assets_after_id。

请求示例

curl "https://wxmp.aicloud.xx.kg/api/v1/management/articles/by-review?book_id=MP_WXS_2398482821&review_id=MP_WXS_2398482821_example~id" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY"

返回说明

正文及媒体返回规则同按文章编号查询；不存在的采集记录返回404。 本接口和按 book_id 查询的文章列表提供 content_attempt，记录最近正文处理结果、失败次数和时间； diagnostics 区分获取、解析或保存阶段及原因，message / suggestion 给出安全中文说明和建议，支持 STORAGE_* 保存错误；旧记录可能没有诊断。

单篇正文失败会继续处理后续文章，下一正常批次再试；已保存正文跳过。 需要主动保存时，可将 original_url 交给管理解析接口并指定保存，该操作会访问微信原文。

读取采集记录与原文链接

返回上一级 · 返回目录

用途：查看跟踪公众号已入库的标题、时间、链接及处理状态。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	book_id 为公众号标识；limit 默认100，范围1～500。

请求示例

curl "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread/subscriptions/MP_WXS_2398482821/articles?limit=100" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY"

返回示例（示意数据）

{
  "items": [{
    "book_id": "MP_WXS_2398482821",
    "review_id": "MP_WXS_2398482821_example~id",
    "title": "文章标题",
    "published_at": 1790635542,
    "original_url": "https://mp.weixin.qq.com/s/...",
    "parse_state": "pending",
    "parse_result": null,
    "error_code": null,
    "first_seen_at": "2026-09-29T04:50:00+00:00",
    "updated_at": "2026-09-29T04:50:10+00:00"
  }]
}

按发布时间倒序返回。published_at 为 Unix 秒，入库时间为带时区的 ISO 时间。 parse_state=pending 表示正文尚未成功解析，error_code 单独记录错误。 该接口不返回全文；读取正文请使用本节前面的接口。

本接口只查库；GET /api/v1/management/providers/weread/books/{book_id}/articles 会请求微信读书获取上游文章列表。

读取运行概览

返回上一级 · 返回目录

用途：汇总账号、周期维护、调度及各公众号最近采集结果。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	无。

请求示例

curl "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread/overview" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY"

返回说明

汇总刷新计划、保活成功/错误/未知结果、调度记录、采集时间表及各公众号最近结果。 时间为带时区的 ISO 格式；未初始化的数据为空，计划时间不保证准点执行，历史结果不代表当前业务可用。

正文未全部成功时批次可为 partial；每号的 collection_complete 表示所选页数处理结束，content_failed/content_failures 提供失败数量和最多10篇诊断样本。 last_collection_at 为列表进度时间，last_successful_round_at 为全部完成时间。 微信读书返回 NEED_VERIFY 时仍停止本轮后续公众号，账号周期刷新独立继续。

其他只读查询：GET /api/v1/management/providers/weread/subscriptions 查看跟踪列表， GET /api/v1/management/providers/weread/pull-round 查看最近批次， GET /api/v1/management/providers/weread/topic-searches/{uid} 查看已保存的话题结果。

改名、暂停或恢复

返回上一级 · 返回目录

用途：修改订阅名称，或控制该号是否参加自动采集。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	请求体中的 name、enabled 至少一项；enabled=false 暂停，true 恢复。

请求示例

curl -X PATCH "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread/subscriptions/MP_WXS_2398482821" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

返回说明

返回修改后的订阅，subscription_status 为 active / paused / cancelled。 恢复也适用于已取消记录，等待下一正常时段，不立即拉取；需要补齐停用期间历史时使用历史补拉。

暂停期间仍可显式手动拉取；同号正在执行任务时返回 409 WORK_BUSY，完成后重试。

取消跟踪

返回上一级 · 返回目录

用途：停止跟踪该公众号，保留历史文章与采集记录。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	路径中的 book_id 必填，无请求体。

请求示例

curl -X DELETE "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread/subscriptions/MP_WXS_2398482821" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY"

返回说明

返回已取消的订阅。列表默认隐藏取消记录，查询时加 include_cancelled=true 可查看。 重复注册不会修改或恢复已有订阅；恢复须显式使用 PATCH 的 enabled=true。 同号正在执行时返回 409 WORK_BUSY。

搜索公众号

返回上一级 · 返回目录

用途：按关键词查找公众号，取得可用于跟踪的公众号标识。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	keyword 必填；count 默认15、最多20；mode 默认为 app，可选 direct。

请求示例

curl -G "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread/search" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY" \
  --data-urlencode "keyword=Wind万得" --data "count=5" --data "mode=app"

返回说明

默认使用模拟应用的搜索流程，返回 items；搜索本身不注册订阅。 需要多页结果时使用 POST /api/v1/management/providers/weread/search-pages。

搜索或文章反查后注册

返回上一级 · 返回目录

用途：从搜索结果或微信文章链接识别公众号并加入跟踪。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	keyword 与 article_url 二选一；slot 从1开始；immediate 可控制首次立即采集。

请求示例

curl -X POST "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread/subscriptions/register-from" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"Wind万得","slot":1,"mode":"app","immediate":false}'

返回说明

返回注册后的订阅。文章反查请求体可写为 {"article_url":"https://mp.weixin.qq.com/s/..."}。 已知标识时使用 POST /api/v1/management/providers/weread/subscriptions，请求体为 {"book_id":"MP_WXS_123","name":"公众号名","immediate":false}，可直接写入订阅。

重复 book_id 不更新原记录。首次立即采集默认关闭，省略 immediate 时使用已保存设置； 即时采集由调度执行，注册接口不会当场拉取。

搜索话题文章

返回上一级 · 返回目录

用途：搜索指定话题、获取原文链接，并可选解析和保存正文。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	keyword 必填；默认1页、每页15条，limit 默认15；parse、save 默认关闭。

请求示例

curl -X POST "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread/topic-searches" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"人工智能","pages":1,"count":5,"resolve_urls":true,"limit":5}'

返回说明

返回搜索条目、已获取的原文链接和结果 uid。 resolve_urls=false 只搜索；indices 可按从1开始的位置选择条目，覆盖 limit 的选取规则。 未提供 indices 时，limit=0 不选取任何条目获取原文链接。

默认避让采集时段前后15分钟，每个凭证刷新窗口最多10次逻辑搜索； force=true 可显式越过这两项限制。默认不抓取正文。

parse=true 解析已获取的链接，要求 resolve_urls=true； save=true 将成功解析的正文存入内容库，要求 parse=true。 正文默认最多尝试3篇，max_articles 可设1～10；软时间预算 content_budget_seconds 默认90秒，在每篇开始前检查，单篇失败继续。

content 单独报告正文结果，正文随本次响应返回。 GET /api/v1/management/providers/weread/topic-searches/{uid} 只读已保存结果和正文处理摘要； 保存成功后按 article_id 从正文查询接口读取。正文阶段只访问微信原文，不再次搜索。

失败项的 diagnostics.reason_code 区分作者隐私、平台限制、发布者删除、网络/HTTP故障、验证码、缺少正文或部分解析；message / suggestion 提供中文说明与建议， stage 表示获取、解析或保存阶段。结果查询也能读取诊断，旧结果不会自动补抓或回填。

保存采集设置

返回上一级 · 返回目录

用途：保存完整业务设置，不立即执行采集。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	请求体包含 enabled、times、immediate_first_pull 和 max_pages。

请求示例

curl -X PUT "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread/pull-settings" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"times":["06:00","12:00","18:00"],"immediate_first_pull":false,"max_pages":1}'

返回说明

返回保存后的设置。GET /api/v1/management/providers/weread/pull-settings 只读当前设置； 出厂默认时段为06:00 / 12:00 / 18:00，以返回的 timezone 为准。

• 每天1～3次，相邻时段含跨午夜至少间隔4小时；首次立即采集默认关闭。
• 每号默认1页，页内文章数不限制。达到页数上限表示本轮策略完成，不保证覆盖当天全部文章。
• enabled 与运行总开关 runtime_enabled 均开启才会自动采集；本接口只改业务设置。
• GET /api/v1/management/providers/weread/pull-round 返回批次 status、results、skipped、next_run_at 等，不触发任务。
• 本轮某号出现 NEED_VERIFY 时跳过余号，周期凭证刷新继续；缺原文链接记录原因并继续其他文章。

手动采集单个公众号

返回上一级 · 返回目录

用途：请求微信读书并保存文章信息和原文链接，可选保存正文。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	pages 默认1；max_articles=0 表示不限文章数；parse=true 才额外解析和保存正文。

请求示例

curl -X POST "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread/subscriptions/MP_WXS_2398482821/pull" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pages":1,"max_articles":0,"parse":false}'

返回说明

返回本次采集结果、处理数量和停止原因。正文失败记录诊断，继续处理后续文章。 自动采集的正文开关由运行配置独立控制，不使用本次请求的 parse 设置。

创建历史补拉

返回上一级 · 返回目录

用途：按指定时间范围补拉历史，不改变正常批次采集进度。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	since、upper 为 Unix 秒；book_ids 可选；pages 默认1，parse 默认 false。

请求示例

curl -X POST "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread/catchups" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"since":1790611200,"book_ids":["MP_WXS_2398482821"],"pages":1,"parse":false}'

返回说明

新补拉会先刷新凭证一次。省略 since 时使用上次整批成功时间，无成功批次时必须指定。 返回 uid 后，用 GET /api/v1/management/providers/weread/catchups/{uid} 只读查询进度， POST /api/v1/management/providers/weread/catchups/{uid}/continue 继续未完成任务。

读取账号状态

返回上一级 · 返回目录

用途：查看保存的账号状态，不触发业务探测或凭证刷新。

鉴权	请求头 X-Wxmpapi-Management-Key
参数	无。

请求示例

curl "https://wxmp.aicloud.xx.kg/api/v1/management/providers/weread" \
  -H "X-Wxmpapi-Management-Key: $WXMPAPI_MANAGEMENT_API_KEY"

返回说明

active 表示凭证已接纳；degraded 表示保留会话但有已记录的异常，原因见 last_error_code。 正常刷新不会导致降级；已有 NEED_VERIFY 等错误保留到业务请求成功。

business_verified 表示当前凭证已有成功业务请求且无已记录错误； active 且该字段为 false 表示已登录、业务待验证。 last_authenticated_at 为最近凭证接纳时间，last_success_at 为最近业务成功时间，刷新和保活不更新后者。

GET /api/v1/management/providers/weread/installation 只读设备档案摘要。