微信公众号上传永久素材接口怎么接？addMaterial 注意事项、格式限制和常见问题

如果你已经开始接微信公众号自动化，另一个很快会遇到的核心问题就是：

永久素材上传接口 addMaterial 到底怎么接，哪些限制最容易被忽略？

这个问题看起来像“上传文件”这么简单，但真正接起来时，最容易出问题的地方通常不是代码本身，而是这些边界条件：

• 这个接口能不能前端直接调
• 图片、语音、视频、缩略图分别支持什么格式
• 为什么有的图片 URL 能返回，但还是不能随便外链使用
• 永久素材库有没有上限
• 图文正文里的图片是不是应该走同一个上传接口

微信官方原始文档：

• 素材管理 / 永久素材 / 上传永久素材（addMaterial）

这篇专门围绕 微信公众号官方 addMaterial 说明，整理新增永久素材时最容易踩的坑。

1. addMaterial 是什么

官方接口英文名是：

addMaterial

调用方式是：

POST https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN&type=image

它的作用是：

把图片、语音、视频、缩略图等文件上传为公众号永久素材。

如果你在做公众号发布链路，可以把它理解成草稿接口之前的重要准备层，因为很多能力都依赖微信认可的素材 id。

2. 第一条规则依然是：只能在服务端调用

官方说明很明确：

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

所以这类调用路径才是对的：

1. 前端把文件或文件引用交给你自己的服务端
2. 服务端准备 access_token
3. 服务端调用 addMaterial
4. 服务端保存返回的 media_id 和必要元数据

如果你把永久素材上传直接放到浏览器、小程序或客户端 App 里做，方向就是错的。

3. type 不是可选项，而且直接决定校验规则

官方查询参数里最关键的是：

• access_token
• type

其中 type 必填，支持这四类：

• image
• voice
• video
• thumb

这不是普通分类字段，而是决定微信如何校验文件格式和大小的关键参数。

也就是说：

• 你不能把视频按图片类型传
• 你不能把封面图和普通图混为一类理解
• 服务端最好在上传前先按 type 做本地校验

4. 各种素材的官方限制一定要前置校验

官方要求和公众平台保持一致，最核心的限制是：

• 图片 image：10MB，支持 bmp/png/jpeg/jpg/gif
• 语音 voice：2MB，时长不超过 60 秒，支持 mp3/wma/wav/amr
• 视频 video：10MB，仅支持 MP4
• 缩略图 thumb：64KB，仅支持 JPG

这里最容易出错的不是“忘了看文档”，而是：

• 本地传了一张超过 64KB 的缩略图
• 视频不是 MP4
• 语音时长超过 60 秒
• 服务端没有按类型做体积和格式检查，直接把错误留给微信接口返回

更稳的做法是，在你自己的服务端就先拒绝明显不合规的文件。

5. 视频上传和图片上传的请求体不是完全一样

官方请求里，media 都是必填的 form-data 字段，但：

• 上传视频时，description 需要一起传
• 上传图片时，通常不需要 description

视频描述对象形如：

{
  "title": "视频标题",
  "introduction": "视频简介"
}

所以如果你在服务端做统一上传封装，至少应该区分：

• 普通素材上传
• 视频素材上传

不要为了“统一接口”把视频的描述信息吞掉。

6. 图片素材返回 URL，但这个 URL 不是通用公网资源

官方说明里有一个特别容易误判的点：

永久图片素材上传后会返回 URL，但该 URL 只能在腾讯系域名内使用，腾讯系域名外使用会被屏蔽。

这意味着你不能简单理解为：

这个理解是错的。

如果你的目标是：

• 给公众号内容使用图片
• 在微信生态内展示

它是合适的。

但如果你的目标是：

• 在任意站外网页长期复用
• 当通用 CDN 外链

那就不应该依赖这个返回 URL。

7. 图文正文图片，不一定应该走这个接口

这也是最常见的误区之一。

官方明确说明：

• 图文消息正文中的外部图片链接会被过滤
• 图文消息图片 URL 应通过“上传图文消息图片接口”获取
• 该接口上传的图片不占用公众号图片素材库 100000 的限制
• 该接口图片仅支持 jpg/png，且大小必须在 1MB 以下

所以这里要严格区分两类场景：

7.1 永久素材库图片

适合：

• 需要沉淀在公众号素材库里的图片
• 封面图、缩略图、素材管理类场景

7.2 图文正文图片

适合：

• 文章内容里的内嵌图片
• 最终需要变成微信正文可用 URL 的图片

这两类不要混用。

如果你把正文图都直接塞成外链，微信会过滤；
如果你把所有图片都先当永久素材处理，也不一定是最合适的正文图路径。

8. 永久素材库是有总量上限的

官方给出的上限是：

• 图文消息素材、图片素材上限为 100000
• 其他类型素材上限为 1000

这决定了如果你做的是批量发布系统，不能默认把公众号素材库当成无限仓库。

更现实的系统设计通常应该考虑：

• 是否真的每次都要沉淀永久素材
• 是否需要本地记录素材用途和来源
• 是否需要在业务侧做素材复用，而不是反复上传同一文件

9. 一个最稳的接入顺序

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

1. 先确认一定是服务端调用
2. 再确认 access_token 有效
3. 再确认 type 与文件真实类型一致
4. 再确认大小、格式、时长都符合微信要求
5. 视频场景再补 description
6. 最后再决定这个素材应该进永久素材库，还是应该走图文消息图片接口

这样做的原因是，最常见的问题往往不是“HTTP 请求不会写”，而是：

• 素材类型选错
• 文件不合规
• 把正文图片和永久素材混为一谈

10. 常见返回和一个容易误导的错误码

官方成功返回里通常会有：

• media_id
• url（仅图片返回）

其中真正关键的是 media_id，因为它才是后续草稿、封面、缩略图等流程里会继续用到的标识。

官方列出的典型错误码是：

• 40007：invalid media_id

这个错误本身很短，但背后通常意味着：

• 你引用了无效素材
• 你在后续接口里用了不符合场景的 media_id
• 你的上传和引用链路没有对齐

所以永久素材上传不应该只盯着“上传成功没”，还要看这个 media_id 后面是否能稳定进入后续接口。

总结

如果你在接微信公众号永久素材上传接口 addMaterial，最该优先记住的是：

• 必须在服务端调用，不能前端直调
• type 决定素材校验规则，不能乱传
• 图片、语音、视频、缩略图各自有明确格式和大小限制
• 视频上传要补 description
• 永久图片返回 URL，但不能当通用公网图床使用
• 图文正文图片应该重点看“上传图文消息图片接口”，不要和永久素材接口混用
• 素材库总量有上限，不能把它当无限仓库

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

• 微信公众号草稿箱新增草稿接口怎么接？draft_add 注意事项、字段限制和常见报错
• 图文消息草稿接口怎么接？从认证头到请求体的最小路径
• Batch Upload
• 联系页