适用对象:有内容系统 / 定时发布需求的开发者。本文以 Python 为例,走通「获取凭证 → 上传封面 → 创建草稿 → 提交发布 → 查询状态」全链路。
40164(IP 不在白名单内)。云服务器建议绑定固定弹性公网 IP。freepublish),文章会进入公众号的「发表记录」、可被搜一搜/推荐抓取,但不会像群发那样推送通知给所有粉丝。需要粉丝通知的是群发接口(message/mass/*),额度和审核规则完全不同,别混用。获取 access_token
│
上传封面图(永久素材)──► thumb_media_id
│
组装正文 HTML(正文图片先走 uploadimg 换 URL)
│
创建草稿 draft/add ──► 草稿 media_id
│
提交发布 freepublish/submit ──► publish_id
│
轮询 freepublish/get 查发表状态 ──► 成功后拿到文章 URL推荐用稳定版接口 cgi-bin/stable_token(与普通 cgi-bin/token 互斥其一即可,稳定版在 token 未过期时重复调用不会挤掉已有 token,更适合多服务共存):
import requests
APPID = "wx************"
SECRET = "********************************"
def get_access_token():
r = requests.post(
"https://api.weixin.qq.com/cgi-bin/stable_token",
json={"grant_type": "client_credential",
"appid": APPID, "secret": SECRET,
"force_refresh": False},
timeout=10,
)
data = r.json()
if "access_token" not in data:
raise RuntimeError(f"获取 token 失败: {data}")
return data["access_token"]access_token 有效期 7200 秒,必须集中存储、统一刷新(如 Redis),不要每台机器各刷一遍互相顶掉。
草稿的封面 thumb_media_id 必须是永久素材 ID:
def upload_thumb(token, path):
with open(path, "rb") as f:
r = requests.post(
"https://api.weixin.qq.com/cgi-bin/material/add_material",
params={"access_token": token, "type": "image"},
files={"media": f},
timeout=30,
)
return r.json()["media_id"]注意:正文内的图片不能直接用外链,也不要用永久素材接口,要用 cgi-bin/media/uploadimg 上传后换成返回的微信域名 URL,再拼进正文 HTML。
def add_draft(token, title, content_html, thumb_media_id, author="", digest=""):
payload = {
"articles": [{
"article_type": "news",
"title": title,
"author": author,
"digest": digest, # 摘要,为空时默认抓正文前 54 字
"content": content_html, # 正文 HTML
"content_source_url": "", # 「阅读原文」链接
"thumb_media_id": thumb_media_id,
"need_open_comment": 0,
"only_fans_can_comment": 0,
}]
}
r = requests.post(
"https://api.weixin.qq.com/cgi-bin/draft/add",
params={"access_token": token},
json=payload,
timeout=30,
)
data = r.json()
if "media_id" not in data:
raise RuntimeError(f"建草稿失败: {data}")
return data["media_id"] # 这是草稿的 media_idimport time
def publish(token, draft_media_id):
r = requests.post(
"https://api.weixin.qq.com/cgi-bin/freepublish/submit",
params={"access_token": token},
json={"media_id": draft_media_id},
timeout=30,
)
data = r.json()
if data.get("errcode") != 0:
raise RuntimeError(f"提交发布失败: {data}")
return data["publish_id"]
def wait_publish_result(token, publish_id, tries=10):
for _ in range(tries):
r = requests.post(
"https://api.weixin.qq.com/cgi-bin/freepublish/get",
params={"access_token": token},
json={"publish_id": publish_id},
timeout=30,
)
d = r.json()
status = d.get("publish_status") # 0 成功 / 1 发布中 / 2 原创失败 / 3 常规失败 / 4 平台审核不通过 / 5 删文 / 6 系统拦截
if status == 0:
return d["article_detail"]["item"][0]["article_url"]
if status != 1:
raise RuntimeError(f"发布未成功, status={status}: {d}")
time.sleep(6)
raise TimeoutError("发布状态长时间未确认,请到后台发表记录核对")freepublish/submit 返回成功只代表提交成功,审核与发表是异步的,一定要用 publish_id 查到 publish_status == 0 才算真发出去,并保存返回的 article_url。
错误码 | 含义 | 处理 |
|---|---|---|
40164 | 调用 IP 不在白名单 | 把服务器出口 IP 加进基本配置的 IP 白名单 |
48001 | 接口功能未授权 | 账号未认证或该接口不在账号权限集内,先做微信认证 |
40007 | 不合法的 media_id | 封面要用永久素材 ID;草稿 media_id 与素材 ID 不要混用 |
45009 | 接口调用频率超限 | token/接口都有日配额,集中缓存 token、控制轮询频率 |
53401/53402 | 发表时内容触发审核/系统拦截 | 查 |
uploadimg 转换,无外链、无本地路径自动发布的本质就是把后台的「写草稿 → 点发表」换成 API 调用:stable_token 拿凭证、永久素材拿封面、draft/add 建草稿、freepublish/submit 提交、freepublish/get 确认结果。链路不长,真正容易踩的坑在权限(认证 + IP 白名单)和异步状态确认这两处,按上面的清单走一遍基本都能一次跑通。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。