微信文章转存API参数详解与工程实践

适用场景在日常工作中经常需要将微信公众号文章内容保存为可编辑的格式例如归档知识库、导入笔记工具如Obsidian、Notion、进行内容二次分析或构建自己的阅读系统。微信文章转存API提供了一种程序化的方式输入文章链接即可获取结构化元数据标题、作者、公众号、发布时间以及完整的Markdown或纯文本正文同时还能下载正文中所有图片资源。典型应用场景包括内容聚合工具定时抓取关注的公众号文章统一存储到本地或云端。知识管理流程将锁定的文章一键转为Markdown嵌入个人知识管理系统。离线阅读同步批量转存后导出为PDF或电子书格式便于无网环境阅读。接口能力边界在接入之前需要了解该API的约束和设计目标请求方式POST数据通过JSON格式的请求体提交。请求地址https://v1.apizero.cn/api/wechat-archiveQPS限制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对象包含以下字段参数名类型必填说明示例值urlstring是微信公众号文章的完整URL需以https://mp.weixin.qq.com/s/开头https://mp.weixin.qq.com/s/hy31xZK6FH3H51qh1zeSKAformatstring否输出格式markdown、text、both。不传时默认行为请参考文档bothtimeoutnumber否内部抓取超时秒数建议设置合理值例如20~30避免网络波动导致请求挂起20参数说明url必须为微信公众号文章的真实链接若链接无效错误格式、已删除或非公开链接接口将返回错误。formatboth会同时返回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, headersheaders, jsonpayload, timeout30) 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, encodingutf-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:0008: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 );5. 错误监控与日志集成统一日志框架记录每次请求的request_id、响应状态码和耗时。在出现批量失败时可以通过request_id快速定位问题区间。参考文档微信文章转存API文档https://apizero.cn/aidocs/wechat-archive原始Markdown文档https://apizero.cn/aidocs/wechat-archive/raw.md如需了解鉴权详情、最新参数变更等请以上述官方文档为准。