最小可运行示例：微信文章转存API实战

适用场景在日常开发中经常需要将微信公众号文章的内容进行存档、分析或二次加工。例如知识管理工具需要将公众号文章自动转为 Markdown 并存入笔记系统数据分析平台需要提取文章标题、作者、发布时间等元数据内容聚合器需要批量抓取多篇文章的正文和图片自动化工作流中需要将文章内容推送到其他平台如博客、邮件简报。微信文章转存 API 正是为解决这类需求而设计它接受一个有效的微信公众号文章链接返回结构化的 Markdown/纯文本内容、文章元数据以及图片资源。本文将以“最小可运行示例”为切入点帮助开发者 10 分钟内完成集成。接口能力边界输入一个有效的微信公众号文章 URL格式通常为https://mp.weixin.qq.com/s/...。输出包括正文可选 Markdown、纯文本或两者、文章元数据标题、作者、公众号名称、发布时间、阅读数、点赞数等、图片列表每个图片的 URL 和文件大小。其中阅读数和点赞数可能为nullAPI 无法获取时。QPS 限制1 请求/秒适合低频或串行调用高并发场景需要自己在客户端控制速率。超时设置可通过timeout参数自定义默认 20 秒。若文章内容或图片较多可适当增大如 60 秒。格式支持markdown仅返回 Markdown 正文、text仅返回纯文本、both同时返回两者。默认值为both。图片处理API 会下载正文中的图片并在images字段返回可直接访问的临时 URL。建议获取后尽快下载到本地或图床因这些 URL 可能有时间限制。请求参数详解认证头Header参数名类型必填说明Authorizationstring是API Key具体格式以官方文档为准。本文示例中使用X-API-Key方式实际可能为Bearer或其他请参考文档。请求体Body请求体为 JSON 对象包含以下字段字段名类型必填默认值说明urlstring是无微信公众号文章链接必须是有效的mp.weixin.qq.com路径。formatstring否both输出正文格式可选markdown、text、both。timeoutnumber否20请求超时秒数建议与后端超时设置一致。注意url必须为 HTTPS 地址且路径中应包含文章唯一标识。如果链接无效或不是公众号文章API 将返回参数错误。最小可运行示例使用 curl在终端中执行以下命令即可发起一次请求。请将YOUR_API_KEY替换为你的真实 API Key。curl -sS \ -X POST \ -H Authorization: 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如果希望仅返回纯文本可将format: text。若只想要 Markdown则设为markdown。返回的 JSON 中content字段会包含对应的数据。提示-sS表示静默输出但显示 HTTP 错误。若要查看完整的响应头可改为-v。不同 format 的请求对比format 值content中出现的字段markdown仅markdowntext仅textbothmarkdown和text选择哪种格式取决于你的后续处理流程若需要保留格式如标题、列表、加粗使用markdown若仅需要纯文本如全文搜索使用text若不确定或两者都需要使用both一次获取。返回值解读响应数据结构分为顶层字段和嵌套data对象。顶层字段字段名类型说明codeint业务状态码0表示成功非0表示失败。具体错误码请参考文档。msgstring状态描述信息例如“成功”或错误原因。request_idstring本次请求的唯一标识可用于日志排查和向技术支持反馈问题。dataobject成功时返回的数据对象失败时可能为null。data 对象字段名类型说明metaobject文章元数据包含title、author、account_name、publish_time、read_num、like_num。其中read_num和like_num可能为null。contentobject正文内容根据format参数提供markdown和/或text字符串。注意 Markdown 内容中的图片引用可能为原始 URL而实际可用的图片链接在images字段中。imagesarray图片资源列表每个元素包含url可直接访问的图片链接和size_bytes文件大小单位字节两个字段。建议优先使用此字段中的 URL 而非 Markdown 中的链接。meta 字段详解title文章标题字符串类型。例如GitHub史上最快破10万星项目来了。author文章作者名字符串。若未显示作者可能为null。account_name公众号名称字符串。publish_time发布时间ISO 8601 格式带时区如2026-05-01T10:00:0008:00。read_num阅读数整数或null。若文章未公开阅读量或 API 未获取到则为null。like_num点赞数整数或null。同理。content 字段详解当format为both时content.markdown包含完整的 Markdown 内容content.text包含纯文本去除了 Markdown 标记。若format为markdown则只有markdown字段若为text则只有text字段。images 字段示例images: [ { url: https://mmbiz.qpic.cn/..., size_bytes: 45000 }, { url: https://mmbiz.qpic.cn/..., size_bytes: 120000 } ]常见错误与排查错误现象可能原因解决方案返回{code: 401, msg: 认证失败}API Key 无效或未传入 Authorization 头检查 API Key 是否正确确认请求头名称和格式是否与文档一致。返回{code: 400, msg: 参数错误}请求体缺少必填字段或 JSON 格式错误确保url字段存在且为合法的 HTTPS 链接JSON 中无多余逗号或引号。超时或长时间无响应文章内容过长或图片数量多默认超时不够增加timeout参数值例如 60 秒。若仍超时说明可能存在网络问题可重试。返回code: 0但meta中部分字段为null该文章未公开对应数据或 API 暂未获取到属于正常情况不影响正文获取。HTTP 状态码 429请求频率超过 QPS 限制暂停 1-2 秒后重试或实现客户端的速率控制。工程化注意事项1. API Key 安全管理永远不要在代码仓库中硬编码 API Key。推荐使用环境变量例如WECHAT_ARCHIVE_API_KEY或密钥管理服务如 Vault、AWS Secrets Manager。在 curl 示例中可以这样引用curl ... -H Authorization: $WECHAT_ARCHIVE_API_KEY ...2. 速率控制QPS 限制为 1即每秒最多一个请求。如果需要批量处理多个文章链接应在请求间加入至少 1 秒的间隔。可以使用sleep(1)bash或time.sleep(1)Python实现或使用节流库如ratelimit。3. 图片持久化返回的图片 URL 是临时有效的建议尽快下载并保存到自己的存储系统。以下是一个 Python 批量下载图片的简单示例结合前面的调用函数import requests import os def download_images(images, output_dir): os.makedirs(output_dir, exist_okTrue) for idx, img in enumerate(images): resp requests.get(img[url], streamTrue) if resp.status_code 200: ext .png # 实际情况可以从 Content-Type 推断 filename fimg_{idx}_{img[size_bytes]}{ext} filepath os.path.join(output_dir, filename) with open(filepath, wb) as f: for chunk in resp.iter_content(1024): f.write(chunk) print(fDownloaded {filepath})4. 错误重试策略对于可重试的错误如超时、HTTP 5xx、网络错误建议使用指数退避重试如 1s、2s、4s最多 3 次。对于不可重试的错误如 400 参数错误、401 认证失败应记录日志并停止重试。5. 编码处理微信公众号文章可能包含 Emoji、数学符号等特殊字符。API 返回的 JSON 已是 UTF-8 编码无需额外转换。但在处理 Markdown 内容时注意不要对 Markdown 语法进行不必要的转义。6. 超时与异步调用如果文章内容很长数千字数十张图片API 处理时间可能超过 30 秒。建议在非阻塞场景下使用异步任务如 Celery、消息队列来调用此 API避免阻塞主线程。7. 用户态参数校验在发送请求前在客户端对url进行格式校验如正则匹配^https://mp\.weixin\.qq\.com/s/可以提前过滤无效请求节省 API 调用次数。使用编程语言调用Python 完整示例import requests import json import os API_URL https://v1.apizero.cn/api/wechat-archive API_KEY os.environ.get(WECHAT_ARCHIVE_API_KEY, YOUR_API_KEY) def archive_wechat_article(url, formatboth, timeout20): headers { Authorization: API_KEY, Content-Type: application/json } payload { url: url, format: format, timeout: timeout } try: response requests.post(API_URL, headersheaders, jsonpayload, timeouttimeout 5) response.raise_for_status() # 触发 HTTP 错误异常 return response.json() except requests.exceptions.RequestException as e: print(f请求失败: {e}) return None if __name__ __main__: test_url https://mp.weixin.qq.com/s/hy31xZK6FH3H51qh1zeSKA result archive_wechat_article(test_url, formatboth) if result and result.get(code) 0: meta result[data][meta] print(f标题: {meta[title]}) print(f作者: {meta[author]}) print(f公众号: {meta[account_name]}) # 图片下载可调用上面的 download_images 函数 # download_images(result[data][images], ./downloads) else: print(调用失败)此示例包含了环境变量读取、异常处理和简单的结果打印。你可以将其作为基础模板集成到自己项目中。总结本文通过最小可运行示例完整演示了微信文章转存 API 的调用流程。从参数说明、curl 示例、返回字段解读到错误处理和工程化注意事项涵盖了开发者在集成过程中最常见的关注点。通过本文你可以快速在自己的项目中实现对公众号文章的抓取和转换。参考文档微信文章转存 API 官方文档原始 Markdown 文档