微信发图片朋友圈接口（多图上传）

前言

做营销自动化或内容运营的开发者，经常需要程序化地往朋友圈发布带图文章。微信官方公众号体系不涉及个人朋友圈，企业微信的"客户朋友圈"又有严格资质门槛。真正能支持个人微信账号发图片朋友圈的接口，只能走iPad协议层的HTTP API。本文从原理到多图上传实操逐步拆解，并给出完整调用范式和常见坑点。

为什么个人朋友圈发图需要走 iPad 协议

微信客户端分为移动端（iOS/Android）、PC端和iPad端。三者与后台通信的协议不同，但功能覆盖最完整的是 iOS 和 iPad 协议——尤其 iPad 协议对发朋友圈、查看好友动态、互动点赞评论的支持最为稳定，且在服务端以"长连接"方式保活时掉线率更低。

走 PC 端协议发朋友圈有一个历史遗留问题：PC 微信长期不支持直接发图片朋友圈，只能发文字或链接；而 iPad 协议模拟的是完整的 iPad 客户端行为，能原生调起"选相册→上传→发布"完整流程，因此多图朋友圈在 iPad 协议下成功率最高。

WechatApi 正是基于这一思路构建的个人微信 HTTP API 平台：底层封装了 微信 iPad 协议 的长连接管理、会话保活与风控策略，开发者只需调用标准 HTTP 接口，不需要关心协议逆向细节。

多图上传的整体流程

在微信内部，发图片朋友圈并不是"把图片和文字一起 POST 过去"这么简单。微信采用的是先上传后绑定的两段式流程：

1. 上传阶段：把每张图片先上传到微信 CDN，拿到每张图片对应的 mediaId（或内部的 filekey）。
2. 发布阶段：构造朋友圈内容，把上传阶段拿到的所有 mediaId 列表附在发布请求的 media_list 字段里，一次性发布。

WechatApi 把这两步都封装成独立接口，开发者可以串行调用，也可以并行上传多张图后统一发布，灵活度很高。

整体调用链路如下：

图片文件（本地/URL）
    ↓
POST /api/moments/upload-image   × N（每张图一次）
    ↓ 返回 mediaId 列表
POST /api/moments/publish
    ↓ 发布成功

所有请求统一使用：

• 鉴权：请求头 VideosApi-token: <你的token>
• 设备标识：body 中的 appId 字段，对应控制台绑定的那台 iPad 设备
• 返回格式：{"ret": 200, "msg": "success", "data": {...}}

第一步：图片上传接口详解

请求方式

bashPOST https://api.wechatapi.net/api/moments/upload-image
Content-Type: application/json
VideosApi-token: YOUR_TOKEN_HERE

请求体参数

单次上传返回示例：

json{
  "ret": 200,
  "msg": "success",
  "data": {
    "mediaId": "wx_media_abc123def456",
    "fileSize": 204800,
    "width": 1080,
    "height": 1440
  }
}

拿到 data.mediaId 后存入数组，为下一步发布做准备。

并行上传多张图的 Python 示例

pythonimport requests
import concurrent.futures

API_BASE = "https://api.wechatapi.net"
TOKEN = "YOUR_TOKEN_HERE"
APP_ID = "YOUR_APP_ID_HERE"

HEADERS = {
    "VideosApi-token": TOKEN,
    "Content-Type": "application/json"
}

def upload_one_image(image_url: str) -> str:
    """上传单张图片，返回 mediaId"""
    payload = {
        "appId": APP_ID,
        "imageUrl": image_url
    }
    resp = requests.post(
        f"{API_BASE}/api/moments/upload-image",
        json=payload,
        headers=HEADERS,
        timeout=30
    )
    result = resp.json()
    if result.get("ret") == 200:
        return result["data"]["mediaId"]
    else:
        raise RuntimeError(f"上传失败: {result.get('msg')}")

def upload_images_parallel(image_urls: list) -> list:
    """并行上传多张图，返回有序的 mediaId 列表"""
    media_ids = [None] * len(image_urls)
    with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
        future_to_index = {
            executor.submit(upload_one_image, url): i
            for i, url in enumerate(image_urls)
        }
        for future in concurrent.futures.as_completed(future_to_index):
            idx = future_to_index[future]
            media_ids[idx] = future.result()
    return media_ids

# 示例：上传 3 张图
image_list = [
    "https://example.com/img1.jpg",
    "https://example.com/img2.jpg",
    "https://example.com/img3.jpg"
]
media_id_list = upload_images_parallel(image_list)
print("已上传，mediaId 列表：", media_id_list)

上面用 ThreadPoolExecutor 并行发出多个上传请求，可以显著减少总耗时。注意 media_ids 用索引占位保证顺序——朋友圈展示图片的顺序由 media_list 数组顺序决定，乱序会导致展示效果不符合预期。

第二步：发布图片朋友圈接口详解

上传完成后，调用发布接口把图片组合成一条朋友圈动态。

请求参数说明

完整发布示例

pythondef publish_moment_with_images(
    media_ids: list,
    content: str = "",
    location_name: str = None
) -> dict:
    """发布图片朋友圈"""
    payload = {
        "appId": APP_ID,
        "content": content,
        "mediaList": media_ids,
        "visible": 0  # 0=所有好友可见
    }
    if location_name:
        payload["locationInfo"] = {
            "name": location_name,
            "latitude": 31.230416,
            "longitude": 121.473701
        }

    resp = requests.post(
        f"{API_BASE}/api/moments/publish",
        json=payload,
        headers=HEADERS,
        timeout=30
    )
    return resp.json()

# 接上一步拿到的 media_id_list
result = publish_moment_with_images(
    media_ids=media_id_list,
    content="周末爬山，风景绝了 ⛰️",
    location_name="黄山风景区"
)
print(result)
# 预期输出：{"ret": 200, "msg": "success", "data": {"momentId": "xxx"}}

返回体中 data.momentId 是这条朋友圈的唯一标识，后续如需删除动态、查询点赞评论，都需要带上这个 ID 调用对应接口。

关键参数与图片规格注意事项

微信对朋友圈图片有隐性的限制规则，不满足时上传可能成功但发布后显示异常：

图片数量：单条朋友圈最多 9 张，超出后微信端会截断或报错。

图片大小：建议单张不超过 5MB；原图上传支持更高分辨率，但超过 25MB 微信服务端会拒绝。

图片分辨率：微信展示时会自动生成缩略图，极长图（高宽比 > 3:1）会被截断展示，需提前裁剪。

格式支持：jpg / png / gif（gif 只支持单张，多图时 gif 会被当作静态图处理）。

内容文字：content 字段最大长度约 1500 个字符，超出会被截断；emoji 正常支持，但个别特殊符号在部分客户端渲染异常。

位置信息：locationInfo 的经纬度需使用 GCJ-02 坐标系（即高德/腾讯地图坐标），而非 WGS-84（GPS 原始坐标），否则显示位置会有偏差。

上传时效：mediaId 通常有效期为 3 天，超期后无法用于发布，需要重新上传。如果你的业务需要预先"囤图"，请在有效期内发布或妥善安排调度逻辑。

多账号批量发图场景实战

WechatApi 支持同一个 Token 下管理多个设备（appId），这在 微信 SCRM 和私域运营场景下非常常见——比如需要多个个人账号同步发布朋友圈来提升触达率。

批量场景的核心逻辑是：每个 appId 独立上传图片、独立发布，不能跨账号共用 mediaId。

pythonDEVICE_LIST = [
    "device_appId_001",
    "device_appId_002",
    "device_appId_003"
]

def publish_to_all_devices(image_urls: list, content: str):
    """向多个设备账号同步发布朋友圈"""
    for device_id in DEVICE_LIST:
        # 每个设备独立上传图片
        media_ids = []
        for url in image_urls:
            payload = {"appId": device_id, "imageUrl": url}
            r = requests.post(
                f"{API_BASE}/api/moments/upload-image",
                json=payload, headers=HEADERS, timeout=30
            )
            media_ids.append(r.json()["data"]["mediaId"])

        # 发布
        pub_payload = {
            "appId": device_id,
            "content": content,
            "mediaList": media_ids
        }
        r = requests.post(
            f"{API_BASE}/api/moments/publish",
            json=pub_payload, headers=HEADERS, timeout=30
        )
        print(f"设备 {device_id} 发布结果：{r.json()}")

publish_to_all_devices(image_list, "新品上架，限时优惠 🎉")

为了避免账号行为过于一致被风控，建议在多账号场景中对发布时间添加随机延迟（time.sleep(random.uniform(5, 30))），模拟正常用户的操作节奏。WechatApi 在底层也内置了一定的行为随机化策略，但业务层的时间分散同样不可省略。

此外，微信二次开发 场景中还经常配合朋友圈发布做评论互动自动化——当某条动态获得好友评论后，自动触发回复，形成完整的运营闭环。

错误码与排查指南

当遇到图片上传成功但发布返回 503 时，优先排查图片内容是否含有敏感信息（二维码、广告文字占比过高、违规图像等），微信服务端会在发布阶段进行内容审核。

小结

微信发图片朋友圈接口的核心链路是：先调上传接口拿 mediaId → 再调发布接口附上 mediaId 列表。整个过程基于标准 HTTP POST + JSON，鉴权只需一个 VideosApi-token 请求头，业务参数中用 appId 区分不同设备账号，返回格式统一为 {"ret":200,"msg":"...","data":{...}}，接入成本极低。

WechatApi 基于 iPad 协议 提供完整的个人微信 API 能力，除朋友圈发布外，还支持消息收发、群管理、好友互动等数十个接口，适合私域运营、SCRM 系统对接、自动化内容分发等场景。如需体验，可访问 https://newmanager.wechatapi.net/dashboard/ 注册试用，官方文档详见 https://post.wechatapi.net。