发文本一条接口就够，发媒体就多了一层：图片、视频、文件、语音都要先上传拿凭证，再把凭证填进消息内容。这篇按"上传、填凭证、发送"的链路把媒体消息讲清楚，重点说说 8MB 分界线和几个容易翻车的凭证填法。

背景痛点

发图片消息最常见的翻车是两种：一种是把本地路径或外网图片链接直接塞进 content，接口返回失败；另一种是凭证拿到了但字段名填错，消息发出去对方收到的却是一段文本。媒体消息的凭证规则比文本消息严格得多，值得单独讲一遍。

原理

媒体消息之所以要两步走，是因为文件先被加密存到 CDN，消息里只传凭证：id 是文件标识，aesKey 是解密密钥，md5 和 size 用于完整性校验。发送时把凭证填进 content，接收方凭同一组凭证取回文件。

上传接口按媒体类型分开：图片用 uploadImage，视频用 uploadVideo（连封面一起传），文件和语音共用 uploadFile，语音必须是 silk 格式。单次请求体最大 8MB，按 base64 编码后计算。

核心实现

图片消息的完整链路（示例代码，需按官方文档校验）：

import base64, requests

def send_image(appid, conversation_id, image_path):
    # 示例代码，需按官方文档校验
    b64 = base64.b64encode(open(image_path, "rb").read()).decode()
    up = requests.post(f"{BASE_URL}/wx-api/api/cdn/uploadImage",
                       headers={"Authorization": f"Bearer {CREDENTIAL}"},
                       json={"appid": appid, "fileB64": b64},
                       timeout=30).json()
    assert up["code"] == 0, up["message"]
    return requests.post(f"{BASE_URL}/wx-api/api/message/sendImage",
                         headers={"Authorization": f"Bearer {CREDENTIAL}"},
                         json={"appid": appid, "conversationId": conversation_id,
                               "content": up["data"]},   # 上传返回的 data 原样填
                         timeout=10).json()

各类型发送时凭证怎么填，差异都在 content 上：图片和视频是上传返回的 data 原样填；文件要把上传返回的 fileId、fileMd5、fileSize 改名为 id、md5、size，再补文件名 name；语音同样改名后再填语音秒数 voiceTime。

超过 8MB 的大文件走另一条异步链路：uploadBigFile 传的是文件的公网 URL，调用后立即返回 requestId 和上传状态，上传完成后凭证通过推送下发，再用发送大文件接口发出。

踩坑

一、朋友圈的图片和视频必须走上传大文件。用普通上传接口拿到的凭证发朋友圈，接口照样返回成功，但内容会被当成纯文本发出去——这是媒体链路里最隐蔽的一个坑。

二、上传小文件时返回的字段名是 fileId 系，发送时要改成 id 系，两套名字长得很像。别用同一个 JSON 两边复用，改名的动作放在封装函数里固定下来。

三、下载和上传是对称的：收到的媒体消息带着 fileId、fileType、aesKey，调下载接口取回解密后的文件。fileType 要按消息类型对号入座，填错会下载失败；下载建议放进队列，同一条消息只下一次。

四、视频的封面就是上传返回里的 thumbUrl 字段，不用单独上传封面图，省一步。

总结

媒体消息的要点可以压缩成一句：按类型选上传接口、按类型填凭证字段、超过 8MB 换异步大文件链路。这篇的接口细节以Eyun 开发文档的 CDN 文件模块为准，动代码前先把上传接口页的请求示例跑一遍，比看十篇教程都管用。