微信文章转存API参数详解与工程实践-开发者社区

适用场景

在日常工作中，经常需要将微信公众号文章内容保存为可编辑的格式，例如归档知识库、导入笔记工具（如Obsidian、Notion）、进行内容二次分析或构建自己的阅读系统。微信文章转存API提供了一种程序化的方式：输入文章链接，即可获取结构化元数据（标题、作者、公众号、发布时间）以及完整的Markdown或纯文本正文，同时还能下载正文中所有图片资源。

典型应用场景包括：

内容聚合工具：定时抓取关注的公众号文章，统一存储到本地或云端。
知识管理流程：将锁定的文章一键转为Markdown，嵌入个人知识管理系统。
离线阅读同步：批量转存后导出为PDF或电子书格式，便于无网环境阅读。

接口能力边界

在接入之前，需要了解该API的约束和设计目标：

请求方式：POST，数据通过JSON格式的请求体提交。
请求地址：https://v1.apizero.cn/api/wechat-archive
QPS限制：1次/秒。超过此频率会返回频率限制错误，建议调用方实现请求排队或指数退避。
超时机制：接口本身支持通过timeout参数设置内部抓取的超时时间（秒），默认值未公开，但建议显式传入如20以避免长时间挂起。
内容格式：支持返回markdown、text或both。Markdown格式会保留文章内的标题、列表、引用等基本的Markdown语法，图片以![]()形式嵌入，但其实际图片链接会同步在data.images字段中提供。
元数据覆盖：返回meta中包含标题、作者、公众号名称、发布时间；read_num和like_num字段可能为null，取决于微信页面当前是否公开显示。

鉴权与请求参数解析

鉴权方式

接口通过HTTP Header进行鉴权，字段名为Authorization，类型为字符串。实际使用时需要将你获得的API密钥拼接成{your_key}传入（具体格式参考官方文档，通常为Bearer Token或纯密钥）。

示例Header配置：

Authorization: sk-your-key-here Content-Type: application/json

注意：部分早期版本文档可能使用X-API-Key，但以当前文档为准，应使用Authorization。建议始终查阅最新文档。

请求体参数

请求体为单个JSON对象，包含以下字段：

参数名	类型	必填	说明	示例值
`url`	string	是	微信公众号文章的完整URL，需以`https://mp.weixin.qq.com/s/`开头	`"https://mp.weixin.qq.com/s/hy31xZK6FH3H51qh1zeSKA"`
`format`	string	否	输出格式：`markdown`、`text`、`both`。不传时默认行为请参考文档	`"both"`
`timeout`	number	否	内部抓取超时秒数，建议设置合理值（例如20~30），避免网络波动导致请求挂起	`20`

参数说明：

url：必须为微信公众号文章的真实链接，若链接无效（错误格式、已删除或非公开链接），接口将返回错误。
format：both会同时返回markdown和text两个字段；markdown仅返回Markdown内容；text仅返回纯文本。注意：纯文本会丢失标题层级和加粗等样式。
timeout：此参数控制API内部向微信服务器发起请求的超时时间，并非整个HTTP请求的超时。建议与客户端超时协同设置，例如客户端设置30秒超时，内部timeout设为25秒。

代码接入示例

1. 使用curl直接调用

以下命令展示如何通过最简洁的方式发起请求，请注意替换Authorization值为你的真实密钥。

curl -sS -X POST \ -H "Authorization: sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{"url": "https://mp.weixin.qq.com/s/hy31xZK6FH3H51qh1zeSKA", "format": "both", "timeout": "20"}' \ "https://v1.apizero.cn/api/wechat-archive"

成功返回后，会得到一个JSON结构（参见下一节“返回值解读”）。

2. 使用Python requests库集成

假设我们需要将结果保存到本地Markdown文件并下载图片，可以编写如下脚本：

import requests import json import time API_URL = "https://v1.apizero.cn/api/wechat-archive" API_KEY = "sk-your-api-key" # 请替换 headers = { "Authorization": API_KEY, "Content-Type": "application/json" } payload = { "url": "https://mp.weixin.qq.com/s/hy31xZK6FH3H51qh1zeSKA", "format": "both", "timeout": 20 } # 注意QPS限制，调用前可适当sleep # time.sleep(1) resp = requests.post(API_URL, headers=headers, json=payload, timeout=30) data = resp.json() if data.get("code") == 0: meta = data["data"]["meta"] content = data["data"]["content"] images = data["data"]["images"] print(f"标题: {meta['title']}") print(f"作者: {meta['author']}") print(f"公众号: {meta['account_name']}") print(f"发布时间: {meta['publish_time']}") # 保存Markdown内容 with open(f"{meta['title']}.md", "w", encoding="utf-8") as f: f.write(content["markdown"]) # 下载图片（可选） for img in images: img_url = img["url"] # 可根据需求下载 img_url 到本地 else: print(f"请求失败: {data.get('msg')}, request_id={data.get('request_id')}")

注意：在实际生产环境中，应当处理网络异常、重试和速率控制。

返回值解读

成功的响应示例：

{ "code": 0, "msg": "成功", "request_id": "req_abc123", "data": { "meta": { "title": "GitHub史上最快破10万星项目来了", "author": "作者名", "account_name": "公众号名", "publish_time": "2026-05-01T10:00:00+08:00", "read_num": null, "like_num": null }, "content": { "markdown": "# 文章标题\n\n正文...", "text": "文章标题\n\n正文..." }, "images": [ { "url": "https://mmbiz.qpic.cn/...", "size_bytes": 45000 } ] } }

字段详解

code：业务状态码。0表示成功，非0表示失败（参见错误码表）。
msg：描述信息，成功时为“成功”，失败时说明原因。
request_id：唯一请求标识，可用于后续问题排查。
data.meta：文章元信息。publish_time为ISO 8601格式（含时区）；read_num和like_num若无法获取则返回null。
data.content：根据请求的format字段返回对应的内容。both模式下同时包含markdown和text。
data.images：正文中所有图片资源的列表，包含原始URL和文件大小（字节）。注意：Markdown内容中的图片链接和此处URL一致，可直接使用。如果需要本地存储，建议通过此列表下载，避免解析Markdown中的链接。

常见错误处理

错误现象	可能原因	解决方案
`code`为`-1`或`http 401`	鉴权失败，Authorization头无效或过期	检查API Key是否正确，确认请求头格式
`code`为`-2`或`http 400`	请求参数错误：url无效、格式不正确或缺少必填字段	验证URL必须是`https://mp.weixin.qq.com/s/`开头；确保JSON格式正确
`code`为`-3`	内部超时或抓取失败	增大`timeout`参数（如30秒），或检查网络是否能够访问微信服务器
`code`为`-4`	文章链接已删除或设置为不可访问	尝试手动在浏览器中打开该链接确认
`http 429`	超出QPS限制	降低请求频率，建议每个请求间隔至少1秒，或使用请求队列

通用处理策略：

所有请求都应该捕获网络层面的异常（如ConnectionError、Timeout）。
根据code执行不同的重试逻辑：对于超时（-3）可以重试1~2次；对于参数错误（-2）不应重试，应检查参数。
记录request_id以便向API提供方反馈问题。

工程化注意事项

在将微信文章转存API集成到实际项目时，以下几个要点值得关注：

1. 速率控制与并发

QPS限制为1次/秒。如果需要批量转存多篇文章，必须实现请求队列或使用time.sleep(1)进行间隔。对于高并发场景，可以考虑为多个API Key分散请求，但需遵循平台使用条款。

2. 超时与重试策略

建议客户端设置一个总超时（如30秒），并搭配指数退避重试：

第一次失败后等待1秒重试。
第二次失败后等待2秒。
最多重试3次。
仍失败则记录日志并跳过。

3. 图片资源管理

返回的images列表包含了每张图片的url和size_bytes。下载图片时需要注意：

微信图片可能有防盗链机制，直接使用requests.get可能被拒绝。可以尝试在请求头中添加Referer: https://mp.weixin.qq.com。
图片文件总量较大时，建议异步下载并使用连接池。
存储时可保留原始URL或自定义命名规则，避免重复下载。

4. 数据持久化

建议将返回的meta、content以及图片的URL映射关系存入数据库（如SQLite或PostgreSQL）。这样既方便检索，又避免重复调用API。例如：

CREATE TABLE wechat_articles ( id INTEGER PRIMARY KEY AUTOINCREMENT, url TEXT UNIQUE, title TEXT, author TEXT, account_name TEXT, publish_time TEXT, markdown_content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );