How to Integrate WeChat `addMaterial`

If you are building WeChat publishing automation, another question appears quickly:

How should the permanent media upload API addMaterial be integrated, and which limits matter in practice?

This looks like a basic upload problem. It is not. The hard parts are usually the rules around media type, file size, downstream usage, and the difference between permanent assets and article-body images.

Official WeChat reference:

• Permanent Material Upload (addMaterial)

What addMaterial does

The official API name is:

addMaterial

The endpoint is:

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

It uploads files as permanent WeChat materials, including:

• images
• voice
• video
• thumbnails

If you are assembling a publish pipeline, this usually sits before draft creation because many later steps depend on WeChat-recognized media ids.

Rule one: call it from the server only

The official docs are explicit:

This API must be called from the server, not directly from a frontend such as a webpage, mini-program, or app client.

The correct structure is:

1. the frontend hands a file or file reference to your server
2. the server prepares access_token
3. the server calls addMaterial
4. the server stores the returned media_id and metadata

If you try to turn permanent media upload into a browser-side request, the integration model is already wrong.

type is required and changes validation

The most important query parameters are:

• access_token
• type

type is required and supports:

• image
• voice
• video
• thumb

This is not a passive category field. It controls how WeChat validates the upload.

That means:

• you cannot send a video as image
• you should not treat a thumbnail as a generic image
• your own backend should validate by type before sending the request upstream

File limits should be enforced before the API call

The official constraints are:

• image: up to 10MB, supports bmp/png/jpeg/jpg/gif
• voice: up to 2MB, no more than 60 seconds, supports mp3/wma/wav/amr
• video: up to 10MB, only MP4
• thumb: up to 64KB, only JPG

In practice, the most common failures are:

• a thumbnail larger than 64KB
• a video that is not MP4
• a voice file longer than 60 seconds
• a backend that skips local validation and lets WeChat reject the file

A stronger implementation rejects obviously invalid files before the upstream request.

Video uploads are not identical to image uploads

The media field is required in form-data across media types, but video uploads also need description.

That object looks like this:

{
  "title": "Video title",
  "introduction": "Video introduction"
}

If your backend tries to flatten everything into one generic media-upload wrapper, video handling is where it usually breaks.

The returned image URL is not a general-purpose public asset URL

This is one of the easiest rules to misread.

For permanent images, the API returns a URL, but that URL is intended for Tencent-domain usage and can be blocked outside the Tencent ecosystem.

So this assumption is wrong:

It is suitable for WeChat-side usage. It is not a general replacement for your own public asset hosting.

Article-body images are a different problem

This is the other major integration mistake.

The official docs state that:

• external image links in article bodies can be filtered
• article-body images should use the dedicated article-image upload interface
• those article images do not consume the permanent image library quota
• article-body images only support jpg/png and must be under 1MB

That creates a strict distinction:

Permanent materials

Better for:

• cover images
• thumbnail-like assets
• material-library scenarios

Article-body images

Better for:

• inline images inside the article content
• images that must survive WeChat body rendering correctly

Do not treat those as one upload path.

The permanent material library has quotas

The official limits are:

• up to 100000 article/image materials
• up to 1000 materials for other types

So if you are building a batch publishing system, do not design as if the material library were an infinite store.

A better system usually asks:

• does this file really need to become a permanent material
• can an existing material be reused
• should usage and origin be tracked on the business side

A stable debugging order

When addMaterial fails, the safer order is:

1. confirm the call is server-side
2. confirm access_token is valid
3. confirm type matches the real file type
4. confirm format, size, and duration limits locally
5. add description for video uploads
6. decide whether this asset belongs in permanent materials or the article-image workflow

That order catches most real failures faster than staring at the final error string.

Closing thought

addMaterial is not hard because multipart upload is hard. It is hard because media type, usage boundary, and downstream rendering are easy to mix together.

If you separate permanent materials from article-body images and validate each media type before upload, the integration becomes much more predictable.