> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 媒体处理

> 上传和发送媒体，了解大小限制和转换，并从收到的消息中下载媒体。

## 限制

| 类型 | 默认最大值 |
| - | - |
| 图片 | 20 MB |
| 文档 (`/send/file`) | 50 MB |
| 视频 | 100 MB |
| 下载媒体(入) | 500 MB |

HTTP 请求正文限制等于视频限制 (100 MB)，所以上传不能超过它。 用 `GET /app/info` (`max_image_size`, `max_file_size`, `max_video_size`)查询实时值。这些限制是编译为默认值；它们没有环境变量。

## 提供媒体的两种方式

每个媒体端点接受一个多部分文件或 GOWA 获取服务器的 URL：

```bash theme={null}
# upload
curl -u admin:changeme -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 -F image=@photo.jpg

# URL
curl -u admin:changeme -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 -F image_url=https://example.com/photo.jpg
```

发送一个或另一个，而不是两个。远程媒体URL必须使用 HTTP 或 HTTPS 并解析到公共地址。 GOWA 阻止循环、私有、本地链接和其他保留目的地，包括重定向目标。上传本地文件作为多部分数据而不是使用内部URL。

## 处理中

GOWA 需要 FFmpeg 和 libwebp 在主机上(两者都在 Docker 图像中)。

| 选项 | Endpoint | 效果 |
| - | - | - |
| `compress` | 图像 (默认 `true`), 视频 (默认 `false`) | 发送前重新编码。 |
| `hd` | 图像，视频 | 以高清画质发送，但不放大分辨率：图片长边最高为 2560 px；视频使用 H.264 编码，分辨率最高为 1280×1280。此设置会覆盖 `compress`。 |
| `view_once` | 图像，视频 | 收件人可以打开一次。 |
| `gif_playback` | 视频 | 作为循环的 GIF 游戏。 |
| `ptt` | 音频 | 发送为语音笔记(按推到对话)。与FFmpeg 转换。 |
| (自动) | 貼圖 | JPG, PNG, WebP 或 GIF 转换为 512×512 WebP 贴纸。WebP 动画必须达到WhatsApp的贴纸限制。 |

`/send/file`发送文件时没有转换。

解码前图像处理检查标题尺寸。接受时间最长的边缘是32,768像素。非JPEG图像的预算为4,000万像素。 JPEG拥有8 000万像素上限加上320 MB 十进制内存预算，所以一些较大的累进或CMYK JPEG被拒绝低于像素最高限额。 原始图像在解码超过预算时可以省略缩略图。交互旋转的旋转旋转图像在[交互信息](https://gowa-docs.mintlify.site/zh/examples/interactive-messages.md)中具有分开的、较小的限制。

## 传入媒体

使用 `WHATSAPP_AUTO_DOWNLOAD_MEDIA=true` (默认)，GOWA 下载传入消息的媒体至`statics/media/` 并将相对路径放入webhook payload：

```json theme={null}
{
  "image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"
}
```

通过 `http://<host>:3000/statics/media/<file>` 获取文件。设置 `WHATSAPP_IGNORE_STATUS_MEDIA=true` 可跳过状态更新中的媒体。

在自动下载后，有效载荷带有WhatsApp CDN URL。通过 GOWA 下载，解密文件：

```bash theme={null}
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/message/3EB0C127D7BACC83D6A3/download?phone=628987654321@s.whatsapp.net"
```

WhatsApp 将媒体保存在其服务器上一段有限的时间。立即下载您需要的。

在 v9.9.0 之后的 GOWA `main` 分支中，显式下载和转发操作可以请求手机重新上传已过期的媒体。手机必须在线且仍保留该文件。GOWA 最多等待 30 秒以获取响应。这也适用于 MCP 的 `download_media` 和 `forward` 操作，以及 [Chatwoot 历史消息导入](https://gowa-docs.mintlify.site/zh/integrations/chatwoot.md#%E5%AF%BC%E5%85%A5%E5%8E%86%E5%8F%B2%E8%AE%B0%E5%BD%95)。

## 存储和清理

路径相对于进程的工作目录；从源码运行时通常为 `src/`，在 Docker 中则为 `/app`。Compose 会将仓库中的 `storages/` 和 `statics/` 目录挂载到 `/app` 下。

| 路径 | 目录 |
| - | - |
| `statics/media/` | 下载webhook 媒体和明确的下载，包括聊天/日期子目录。 |
| `storages/<timestamp>-<uuid>[.<extension>]` | 启用自动下载时输入图像处理器保存的额外副本。 |
| `storages/scheduled/` | 由预定发送保留的附件。让调度器管理这些附件。 |
| `storages/history-*.json` | 历史转储，独立于媒体下载。 |

目前没有按存储时长设置的媒体保留选项，也没有清理端点。同一张图片可能在 `storages/` 和 `statics/media/` 中各有一份副本。切勿为了回收媒体空间而删除整个 `storages/` 目录。

暂停 GOWA 和其他作者，备份所需的文件，然后预览文件以移除。 此 GNU 找到从部署目录运行的示例，选择至少31天前的文件。

```bash theme={null}
find ./statics/media -type f -mtime +30 -print
find ./storages -maxdepth 1 -type f -mtime +30 \
  -name '[0-9]*-????????-????-????-????-????????????*' -print
```

检查每条路径后，将上述命令中的 `-print` 替换为 `-delete`。请保留数据库文件、SQLite 的 `-wal` 和 `-shm` 辅助文件、定时任务的附件以及自定义文件。随后重启 GOWA。删除后的路径及其静态 URL 将无法访问，删除媒体也不会清除聊天记录。

`WHATSAPP_AUTO_DOWNLOAD_MEDIA=false` 会停止后续的自动下载和额外的图片副本生成。它不会删除旧文件，也不会阻止通过 REST 或 MCP 显式下载。参阅完整的[媒体存储和清理指南](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/media-storage.md)。

`/statics`仍然是公开的。已保存的 HTML、SVG、脚本和其他文档都被用作`application/octet-stream`和`nosniff`的附件。 图像预览路径支持的图像字节可以内嵌。 这些内容保护并不限制谁可以下载文件。在反向代理上保护敏感媒体。

## 故障排除

| 问题 | 修复 |
| - | - |
| `413` 或 bodlimit 错误 | 文件超过 100 MB；发送链接。 |
| 语音笔记失败或作为文件播放 | 安装 FFmpeg; 设置 `ptt=true` 。 |
| 貼圖转换失败 | 安装 libwebp 工具 (`cwebp`, `dwebp`, `webpmux`). |
| URL 媒体失败 | URL 必须公开，直接返回文件 (没有 HTML 页面) 并符合大小限制。 |


## Related topics

- [正在发送消息](https://gowa-docs.mintlify.site/zh/examples/sending-messages.md)
- [错误处理](https://gowa-docs.mintlify.site/zh/advanced/error-handling.md)
- [WhatsApp 频道](https://gowa-docs.mintlify.site/zh/examples/newsletters.md)
- [正在接收消息](https://gowa-docs.mintlify.site/zh/examples/receiving-messages.md)
- [API 参考](https://gowa-docs.mintlify.site/zh/api-reference/introduction.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.