微信公众平台调用手册
按类型读取永久图片素材
分页查找自己账号的永久图片、语音、视频或图文素材,不上传或删除素材。
← 返回平台功能接入准备
- 已完成 stable_token 手册,把同一账号的有效后台凭证设置为 WX_ACCESS_TOKEN。
- 在微信开发者平台的 接口权限与额度 核对该读取接口已开放,账号中已有相应草稿或永久素材。
准备环境变量
示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。
WX_ACCESS_TOKEN- 同一账号的有效后台 token,不是网页 OAuth 用户 token。
export WX_ACCESS_TOKEN='REPLACE_WITH_BACKEND_ACCESS_TOKEN'以上 export 适用于 macOS / Linux 的终端。按调用步骤保存代码文件,再在同一终端执行。
调用步骤
- 01
设置 WX_ACCESS_TOKEN,先使用 offset=0、count=20 读取第一页。
- 02
本例 type=image;按需要改为 voice、video 或 news,分别解析相应返回结构。
- 03
继续分页时用已读取的 item_count 推进 offset;item_count=0 或已覆盖 total_count 时停止,列表变更时自行去重。
调用 01
按类型读取永久图片素材
使用 POST 请求读取分页列表。该接口不包含临时素材;不同 type 的 item 字段不完全相同。
POST
https://api.weixin.qq.com/cgi-bin/material/batchget_material?access_token=${WX_ACCESS_TOKEN}请求头
Content-Typeapplication/json
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
access_tokenQuery | string必填 | 当前账号后台凭证;注意避免记录完整请求 URL。 |
offset请求体 | number必填 | 从 0 开始的素材偏移。 |
count请求体 | number必填 | 每页 1 到 20 条。 |
type请求体 | string必填 | image、voice、video 或 news;本例查询 image。 |
调用代码
替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。
cat > request-body.json <<'JSON'
{
"type": "image",
"offset": 0,
"count": 20
}
JSON
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.weixin.qq.com/cgi-bin/material/batchget_material?access_token=${WX_ACCESS_TOKEN}" \
--header "Content-Type: application/json" \
--data-binary @request-body.json
import json
import os
import re
import urllib.request
import urllib.error
def expand(value):
return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
lambda match: os.environ[match.group(1)], value)
url = expand("https://api.weixin.qq.com/cgi-bin/material/batchget_material?access_token=${WX_ACCESS_TOKEN}")
headers = {
"Content-Type": expand("application/json"),
}
body = {
"type": "image",
"offset": 0,
"count": 20,
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
try:
with urllib.request.urlopen(request, timeout=30) as response:
result = json.load(response)
except urllib.error.HTTPError as error:
print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
if isinstance(result, dict) and "errcode" in result and result["errcode"] != 0:
raise SystemExit("平台返回业务错误,请结合下方排错说明检查响应")
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
return process.env[name];
});
}
const url = expand("https://api.weixin.qq.com/cgi-bin/material/batchget_material?access_token=${WX_ACCESS_TOKEN}");
const headers = Object.fromEntries(
Object.entries({
"Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
"type": "image",
"offset": 0,
"count": 20
};
const response = await fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
if (Object.hasOwn(result, "errcode") && result["errcode"] !== 0) {
throw new Error('平台返回业务错误,请结合下方排错说明检查响应');
}
返回示例
图片素材结构示意。永久素材 ID 与临时素材 ID 不通用,url 不应当作自己永久可控的对象存储。 以下为结构示意,非本站实测结果。
{
"total_count": 1,
"item_count": 1,
"item": [
{
"media_id": "MEDIA_ID_EXAMPLE",
"name": "cover.png",
"update_time": 1792022400,
"url": "https://mmbiz.qpic.cn/EXAMPLE"
}
]
}常见错误与排查
40001 / 42001凭证无效或已过期- 使用当前账号的有效后台 access_token,检查统一缓存与过期刷新;不要使用网页 OAuth token。
48001接口未授权- 到该账号的 接口权限与额度 核对具体权限,不因成功获取 token 就假定草稿或素材可用。
45009调用超过额度- 降低轮询并核对后台额度;暂停重试,避免错误循环消耗更多调用。
调用注意
- 接口官方适用范围列出公众号与服务号,但仍要核对自己的账号授权。
- 列表正在变动时分页可能重叠或遗漏,归档任务需要按 media_id 和 update_time 去重。
- 原始接口返回的字段可能比本页节选多,以当前响应结构为准;空列表不等于接口错误。
注意事项
- 只读取自己账号资源,不获取其他公众号文章全文或后台草稿。
- 示例采用手动 offset 分页,避免自动无限循环耗尽额度。
- 代码语法检查不能证明真实账号权限、费用或接口调用已成功。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01获取稳定版接口调用凭据核验日期 2026-10-15
- 02公众号接口调用额度说明核验日期 2026-10-15
- 03开发接口管理迁移与权限管理入口核验日期 2026-10-15
- 04获取永久素材列表核验日期 2026-10-15
