微信公众号草稿箱新增草稿接口怎么接？draft_add 注意事项、字段限制和常见报错

如果你已经在做公众号自动化，迟早会遇到一个非常具体的问题：

微信公众号草稿箱新增草稿接口 draft_add 到底怎么接，最容易踩哪些坑？

这个问题比“草稿 API 是什么”更接近真实接入，因为一旦你真正开始调接口，就会马上遇到这些细节：

• 这个接口能不能前端直接调
• 图文消息和图片消息结构是不是一样
• content 里能不能直接放外链图片
• 封面图和正文图各自需要什么素材 id
• 商品卡片为什么会报错

微信官方原始文档：

• 草稿管理 / 新增草稿（draft_add）

这篇专门围绕 微信公众号官方 draft_add 说明，整理新增草稿时最容易被忽略的接入注意事项。

1. draft_add 是什么

官方接口英文名是：

draft_add

调用方式是：

POST https://api.weixin.qq.com/cgi-bin/draft/add?access_token=ACCESS_TOKEN

它的作用很明确：

把图文消息或图片消息新增到公众号草稿箱。

这意味着它解决的不是“排版转换”，而是“把内容真正推进到草稿箱”。

如果你还在区分：

• Markdown 转微信 HTML
• 图文消息草稿

可以先看：

• 微信公众号草稿 API 是什么？为什么它比“只转 HTML”更有价值
• 图文消息草稿接口怎么接？从认证头到请求体的最小路径

2. 最先要记住的限制：只能在服务端调用

这条是最重要的。

根据官方说明，这个接口：

应在服务器端调用，不可在前端（小程序、网页、APP 等）直接调用。

所以如果你准备这样做：

• 浏览器直接请求微信接口
• 小程序里直接请求 draft_add
• 客户端 App 里直接带 token 调用

那方向就是错的。

更稳的结构应该是：

1. 前端把内容提交到你自己的服务端
2. 服务端获取或刷新 access_token
3. 服务端再去调用 draft_add

这也是为什么像 md2wechat Agent API 这类服务，会强调接口必须放在服务端接入，而不是暴露给前端。

3. 新增到草稿箱，不等于永久保存

官方还有两个很容易被忽略的行为说明：

1. 上传到草稿箱中的素材，一旦被群发或发布，就会从草稿箱移除
2. 新增草稿后，可以在公众号平台官网的草稿箱里查看和管理

这两个点决定了你的系统设计不能假设：

• 草稿箱是永久仓库
• 同一个 media_id 会一直留在那里

更现实的理解应该是：

• 草稿箱是“发布前状态”
• 不是长期存储层

如果你要做自动化工作流，草稿创建成功后最好自己保存业务侧记录，而不是完全把“是否存在”托管给微信草稿箱。

4. 请求体里最关键的结构是什么

官方请求体的核心字段是：

{
  "articles": [
    {
      "article_type": "news",
      "title": "标题",
      "content": "正文 HTML 或正文内容"
    }
  ]
}

但这里真正容易出问题的是：
articles 里不同类型的结构并不一样。

官方支持两类：

• news：图文消息
• newspic：图片消息

如果你把两者当成同一种结构处理，接入时很容易出错。

5. news 图文消息最容易踩的几个坑

5.1 title、author 不要传 Unicode 转义字符串

官方特别强调：

• 不要传 "\u4f5c\u8005\u540d" 这种形式
• 直接传正常字符串即可

也就是说，服务端在处理标题和作者时，应该传真实字符，而不是手动再做 Unicode 转义。

5.2 content 不是“任意 HTML 都能过”

官方说明里，content 的约束非常关键：

• 支持 HTML 标签
• 必须少于 2 万字符
• 小于 1 MB
• 会去除 JS
• 涉及图片 URL 时，必须来自“上传图文消息内的图片获取 URL”接口
• 外部图片 URL 会被过滤

这意味着一个常见误区是：

实际上不行。

如果正文里还是外部图片地址，微信会过滤掉。
所以图文消息真正稳定的路径通常是：

1. 先准备微信可接受的图片 URL 或素材
2. 再生成最终内容
3. 最后调用草稿接口

如果你已经在用自己的发布服务，这也是为什么“图片处理”和“草稿创建”通常要拆成两步，而不是一个接口里糊过去。

5.3 thumb_media_id 不是可选心态字段

官方说明里，article_type = news 时：

• thumb_media_id 必填
• 而且必须是永久 MediaID

这意味着封面图不是简单传一个公网 URL 就结束。
它需要先变成微信认可的永久素材 id。

6. newspic 图片消息和图文消息不是一回事

如果你接的是 newspic，重点会转到这些字段：

• image_info.image_list
• cover_info.crop_percent_list
• product_info.footer_product_info.product_key

这里有两个实际约束特别值得注意：

6.1 图片消息最多 20 张图

官方说明里明确写了：

• 图片消息里的图片数量最多为 20 张
• 首张图片即为封面图

如果你做的是内容工厂或批量生成，服务端在提交前最好先做数量校验，不要把超量图片直接交给微信接口报错。

6.2 商品卡片不是所有账号都能直接用

如果你在图片消息里插商品相关信息，官方给了三类典型报错：

• 53404：账号已被限制带货能力
• 53405：插入商品信息有误
• 53406：请先开通带货能力

这几个错误码的含义很直接：

商品卡片能力不是“字段传对了就行”，还依赖账号侧的带货能力和商品状态。

所以如果你计划把商品卡片放进草稿生成链路，服务端最好提前区分：

• 普通图文草稿
• 带商品卡片的图片消息草稿

这两类不要当成同一条默认流程。

7. 裁剪字段为什么容易出问题

官方提供了两类裁剪方式：

• 图文消息封面裁剪：pic_crop_235_1、pic_crop_1_1
• 图片消息封面裁剪：cover_info.crop_percent_list

这些字段都不是像素坐标，而是：

• 以左上角 (0,0)、右下角 (1,1) 为坐标系
• 传归一化比例坐标

这意味着如果你把前端像素裁剪框的值直接原样传过去，通常不对。

更稳的做法是：

1. 前端拿到像素裁剪框
2. 服务端或前端先换算成比例坐标
3. 再按微信要求拼成对应字段

如果没有裁剪需求，就不要为了“看起来更完整”硬塞裁剪参数。

8. 接入时最容易忽略的排错顺序

实际接 draft_add 时，建议按这个顺序排：

1. 先确认接口一定在服务端调用
2. 再确认 access_token 有效
3. 再区分是 news 还是 newspic
4. 再检查封面素材和正文图片来源是否符合微信要求
5. 最后再检查商品卡片和裁剪字段

这样做的原因是，真正最常见的问题通常不是“JSON 写错了”，而是：

• 调用位置错了
• 图片来源不符合微信要求
• 封面素材不是永久 MediaID
• 账号没有商品能力

9. 一个更实用的理解方式

可以把 draft_add 理解成：

• 它不是“富文本保存接口”
• 它是“把合规内容推入公众号草稿箱”的接口

所以它依赖的不只是正文本身，还依赖：

• 服务端调用位置
• token
• 素材体系
• 图片来源
• 账号能力

很多团队最后会把这层封装成自己的服务端能力，而不是让每个业务方直接碰原始微信接口。

总结

如果你在接微信公众号草稿箱新增草稿接口 draft_add，最该优先记住的是这几件事：

• 必须在服务端调用，不能前端直调
• 草稿发布后会从草稿箱移除
• news 和 newspic 的结构不同
• 图文消息里的图片 URL 不能直接用外链
• thumb_media_id 必须是永久 MediaID
• 商品卡片能力依赖账号状态，常见报错是 53404、53405、53406

如果你要把这层能力接入更完整的 Agent 工作流，建议继续结合下面这些内容一起看：

• 图文消息草稿接口怎么接？从认证头到请求体的最小路径
• 微信公众号草稿 API 是什么？为什么它比“只转 HTML”更有价值
• Batch Upload
• 联系页