--- title: "WhatsApp API媒体消息：支持的文件类型与大小限制" description: "WhatsApp API媒体文件大小限制与支持的文件类型：图片、视频、音频、文档和贴纸，以及上传与链接发送的区别、媒体ID和说明文字的用法。" canonical: "https://omnichannels.ai/zh/blog/whatsapp-media-messages-file-types-size-limits/" language: "zh" updated: "2026-11-07" publisher: "BroadNet Technologies" brand: "OmniChannels.ai" category: "whatsapp" primaryQuery: "WhatsApp API媒体文件大小限制" keywords: ["WhatsApp API支持的文件类型", "WhatsApp Cloud API媒体", "WhatsApp视频大小限制", "WhatsApp文档大小限制", "WhatsApp贴纸尺寸", "WhatsApp媒体ID有效期", "WhatsApp模板头部图片", "WhatsApp错误131053"] published: "2026-11-07" author: "OmniChannels.ai Editorial Team" reviewer: "BroadNet Messaging Solutions Team" readingMinutes: 9 answer: "据Meta文档，截至撰文时WhatsApp Cloud API的媒体大小上限为：图片5 MB（JPEG、PNG、静态WebP），视频16 MB（H.264与AAC编码的MP4或3GPP），音频16 MB，文档100 MB，动态贴纸500 KB，静态贴纸100 KB。建议先上传文件再发送媒体ID，而不是发送链接，并确认MIME类型与文件一致。" takeaways: ["据Meta文档，截至撰文时的大小上限为：图片5 MB，视频和音频16 MB，文档100 MB，贴纸500 KB（动态）或100 KB（静态）。", "视频必须是H.264编码并配AAC音频，图片必须是8位RGB或RGBA；文件大小达标，仍可能因编码或色彩格式被拒。", "Meta建议用媒体ID发送已上传的媒体，而不是用链接，以获得更好的性能。", "上传返回的媒体ID30天后过期，而入站Webhook中收到的ID7天后过期，所以请及时下载客户发来的文件。", "图片、视频和文档的说明文字上限为1,024个字符，错误131053通常表示MIME类型与文件不符。"] faq: - q: "WhatsApp API的文件大小限制是多少？" a: "视类型而定。Meta文档列出：图片5 MB，视频和音频16 MB，文档100 MB，动态贴纸500 KB，静态贴纸100 KB。Cloud API的媒体上限为100 MB。限制可能变化，所以在构建校验规则之前，请先对照Meta最新的媒体参考文档确认。" - q: "WhatsApp Business API支持哪些文件类型？" a: "图片：JPEG、PNG和静态WebP。视频：H.264视频加AAC音频的MP4和3GPP。音频：AAC、AMR、MP3、M4A和Opus编码的OGG。文档：TXT、XLS、XLSX、DOC、DOCX、PPT、PPTX和PDF。贴纸：仅限WebP。这些列表之外的格式都会被拒绝，所以发送前请先转换。" - q: "媒体应该用链接发送还是用媒体ID发送？" a: "Meta文档建议使用已上传的媒体ID，以获得更好的性能。链接必须指向公共服务器上的文件，平台要在发送时去抓取；而ID指向的是已存放在Meta的文件。上传所得的ID有效期为30天，到期后必须重新上传。" - q: "WhatsApp媒体ID的有效期是多久？" a: "Meta文档规定：上传媒体时返回的ID为30天，入站Webhook中收到的媒体ID为7天。上传的文件除非提前删除，否则保存30天。通过媒体ID取得的下载URL5分钟后失效，所以每次需要文件时都请重新获取URL。" - q: "可以给WhatsApp图片或视频加说明文字吗？" a: "可以。据Meta的消息参考文档，图片、视频和文档消息可带一个可选的说明文字，最长1,024个字符。音频和贴纸消息没有说明文字。如果想在贴纸或语音消息之外附带文字，请在其后另发一条文本消息。" - q: "WhatsApp错误131053是什么意思？" a: "Meta将其描述为无法上传消息中使用的媒体。常见原因是MIME类型与文件扩展名不符，或类型不受支持。请查看相关Webhook中的错误详情，对照Meta支持的媒体类型确认格式，必要时重新编码文件。" sources: - title: "Media — WhatsApp Business Platform, Meta for Developers" url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media" - title: "Image messages — WhatsApp Business Platform, Meta for Developers" url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/image-messages" - title: "Video messages — WhatsApp Business Platform, Meta for Developers" url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/video-messages" - title: "Document messages — WhatsApp Business Platform, Meta for Developers" url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/document-messages" - title: "Error codes — WhatsApp Business Platform, Meta for Developers" url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes" --- # WhatsApp API媒体消息：支持的文件类型与大小限制 Canonical: https://omnichannels.ai/zh/blog/whatsapp-media-messages-file-types-size-limits/ Language: zh Publisher: OmniChannels.ai by BroadNet Technologies 本指南面向通过WhatsApp Business API发送图片、视频、音频、文档或贴纸、希望避免发送失败的开发者和营销人员。内容列出Meta文档规定的文件类型和大小限制，说明上传与链接、媒体ID、说明文字和模板头部，并介绍如何处理客户发来的文件。 下列数字均为Meta在撰文时（2026年11月7日）文档中的数值。Meta可能随时调整，请以[媒体参考文档](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media)为准。 ## WhatsApp API的媒体文件大小限制是多少？ 每种媒体类型都有各自的上限，Cloud API对任何媒体的上限是100 MB。文档的空间最大，贴纸最小。 | 媒体类型 | 最大大小 | 备注 | |---|---|---| | 图片 | 5 MB | 仅限8位RGB或RGBA | | 视频 | 16 MB | H.264视频，AAC音频 | | 音频 | 16 MB | 多种格式，见下文 | | 文档 | 100 MB | Office、PDF和文本文件 | | 贴纸（动态） | 500 KB | 仅限WebP | | 贴纸（静态） | 100 KB | 仅限WebP | 文件即使满足大小限制，仍可能因格式而失败。接下来的各节会列出每种类型可接受的格式。 ## 支持哪些图片和贴纸格式？ 图片可以是JPEG、PNG或静态WebP，最大5 MB，并且必须是8位RGB或RGBA。贴纸必须是WebP。 | 类型 | 扩展名 | MIME类型 | |---|---|---| | JPEG | .jpeg | `image/jpeg` | | PNG | .png | `image/png` | | 静态WebP | .webp | `image/webp` | Meta对图片还有三条规则。在图片消息中发送的静态WebP会被转码为JPEG。动态WebP文件、无法解码的WebP文件，以及任一边超过4,096像素的图片都会被拒绝。贴纸请使用MIME类型为`image/webp`的WebP：动态的最大500 KB，静态的最大100 KB。 如果品牌素材是设计工具导出的大尺寸PNG，请导出一份适合网页尺寸的JPEG来发送，而不是发原图。 ## 支持哪些视频和音频格式？ 视频为MP4或3GPP，最大16 MB。音频可以是AAC、AMR、MP3、M4A或Opus编码的OGG，同样最大16 MB。 | 类型 | 扩展名 | MIME类型 | |---|---|---| | MP4视频 | .mp4 | `video/mp4` | | 3GPP视频 | .3gp | `video/3gpp` | | AAC音频 | .aac | `audio/aac` | | AMR音频 | .amr | `audio/amr` | | MP3音频 | .mp3 | `audio/mpeg` | | MP4音频 | .m4a | `audio/mp4` | | OGG音频 | .ogg | `audio/ogg` | 对于视频，Meta要求使用H.264编码和AAC音频，且音频流只能有一路或没有。Meta还建议避免使用带B帧的H.264 "High"档次，因为Android版WhatsApp客户端不支持；请使用不带B帧的"Main"档次，或"Baseline"。要把`moov`数据块放在`mdat`数据块之前，使用ffmpeg时即加上`-movflags faststart`选项。 对于OGG，只支持Opus编码，不支持基础的`audio/ogg`类型，并且输入必须是单声道。 ## 支持哪些文档格式？ 文档可以是PDF、Word、Excel、PowerPoint或纯文本，最大100 MB。 | 类型 | 扩展名 | MIME类型 | |---|---|---| | PDF | .pdf | `application/pdf` | | Word | .doc, .docx | `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | | Excel | .xls, .xlsx | `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | | PowerPoint | .ppt, .pptx | `application/vnd.ms-powerpoint`, `application/vnd.openxmlformats-officedocument.presentationml.presentation` | | 文本 | .txt | `text/plain` | 文档消息可以带一个含扩展名的可选文件名，WhatsApp客户端会根据该扩展名选择文件图标。请取一个易读的名称，例如`invoice-2026-1042.pdf`，因为客户会看到它。 ## 应该上传媒体还是发送链接？ Meta建议先上传文件，再发送其媒体ID。您也可以改为发送指向公共服务器上文件的链接，但Meta在图片、视频和文档的参考文档中都说，为了更好的性能应优先使用已上传的ID；在其吞吐量指南中，对大批量发送也是同样的建议。 | | 媒体ID | 链接 | |---|---|---| | 工作方式 | 先上传，再引用返回的ID | 指向公共URL；发送时才抓取文件 | | Meta的建议 | 推荐 | 支持，但不推荐 | | 有效期 | 上传后30天 | 只要您的服务器持续提供该文件 | | 失败模式 | ID过期或无效 | URL无法访问、过慢或类型有误 | 使用Meta自己的端点时，上传是向`//media`发起`POST`，附上文件、其MIME类型和`messaging_product=whatsapp`，响应为`{"id": ""}`。上传的文件会加密保存30天，除非您提前删除。 在OmniChannels.ai的WhatsApp端点上，媒体消息接受`mediaUrl`（公共HTTPS URL）或`mediaFile`（随请求上传的文件），说明文字放在`content`中。请参阅[WhatsApp API文档](/developers/whatsapp/)。大批量发送时，账户如何处理媒体的存储与复用，请咨询我们的团队。 ## 媒体ID的有效期是多久？ Meta规定：上传所返回的ID为30天，入站Webhook中收到的ID为7天。通过ID取得的下载URL在5分钟后失效。 实际影响如下： - 不要把媒体ID缓存数月。请保存原始文件，在ID被拒绝时重新上传。 - 事件一到就下载入站文件，并保留自己的副本。 - 不要保存取得的下载URL；需要时再请求新的。 ## 媒体消息可以加说明文字吗？ 可以。据Meta的消息参考文档，图片、视频和文档消息接受一个可选的说明文字，最长1,024个字符。说明文字是紧挨着文件的纯文本。 在这一模型中，音频和贴纸消息没有说明文字。如果语音消息需要配文字，请在旁边另发一条简短的文本消息。在[客户服务窗口](/zh/blog/whatsapp-24-hour-customer-service-window/)内，说明文字可以自由编写；窗口之外，媒体必须放在已获批的模板中发送。 ## 消息模板中的媒体如何使用？ 模板的头部可以放图片、视频或文档，且该头部在创建模板时就已确定。提交模板审核时需要提供示例文件，发送时则可以提供实际文件。 在我们的API中，创建时`headerFormat`可以是`IMAGE`、`VIDEO`或`DOCUMENT`，`headerFile`用于传递示例，发送时的`mediaUrl`会覆盖头部媒体。示例文件的要求请查阅Meta的模板文档。请参阅[模板类别与审核](/zh/blog/whatsapp-template-categories-approval/)和[模板示例](/zh/blog/whatsapp-message-template-examples/)。 ## 如何下载客户发来的媒体？ 入站媒体以带有媒体ID的Webhook形式到达；您需要把它解析为URL，并带授权下载。 1. 从入站消息事件中读取媒体ID。 2. 请求该ID对应的媒体URL。Meta的响应包含`url`、`mime_type`、`sha256`和`file_size`。 3. 向该URL发送`GET`请求，并带上`Authorization: Bearer `请求头。没有令牌，请求会失败。 4. 检查`Content-Type`请求头和`sha256`值，然后保存文件。 5. 如果返回`404`，请求新的URL并重试；若仍失败，请更新访问令牌。 Meta在Cloud API上的入站媒体最大为100 MB。更大的文件会触发带有错误码`131052`的Webhook；请让客户发送更小的文件，或用其他方式分享。在内部打开之前，请扫描每个文件。请参阅[Webhook指南](/zh/blog/whatsapp-webhooks-guide/)，并向您的开通工程师确认入站媒体在您账户上是如何投递的。 ## 示例：牙科诊所发送报告 开罗的"Nile Smile Clinic"（虚构）会发送预约卡和X光报告。 1. 预约卡是300 KB的PNG图片，配两行说明文字，远低于5 MB。 2. 治疗报告是2到8 MB的PDF，命名为`report-2026-0381.pdf`，以文档形式发送。 3. 一段25 MB的诊所介绍视频超出视频上限。团队将其重新编码为H.264/AAC的MP4，加上`faststart`，大小控制在16 MB以内。 4. 患者发来处方照片。收件箱会立即下载每个文件，因为入站ID在7天后过期。 5. 语音问候被导出为单声道Opus OGG，因为其他OGG变体会被拒绝。 ## 常见错误有哪些？ - **只看大小。**一张色彩格式不对的3 MB图片，或编码有误的视频，照样会失败。 - **MIME不匹配。**把`.jpg`以`application/octet-stream`提供，是错误131053的典型原因。 - **链接指向缓慢或私有的URL，**例如已过期的签名链接，或需要登录才能访问的页面。 - **依赖旧的媒体ID。**ID在30天后过期。 - **忽视入站过期。**客户的文件必须在7天内保存。 - **把动态WebP当图片发送。**它会被拒绝；请改用贴纸或视频。 - **限制会变化。**硬编码校验之前，请重新核对Meta的参考文档。 ## OmniChannels.ai如何提供帮助 OmniChannels.ai通过一个API发送WhatsApp图片、视频、音频、文档和贴纸消息，支持公共链接或上传文件并附说明文字，也会在共享收件箱中显示媒体和附件。BroadNet是Meta官方的商业解决方案提供商（Business Solution Provider），因此带图片、视频或文档头部的模板可以创建，并跟踪其审核状态。请阅读[WhatsApp API文档](/developers/whatsapp/)和[错误与限制](/developers/errors-and-limits/)，或了解[WhatsApp渠道](/zh/channels/whatsapp-business-api/)。