跳转到内容

视频与图片画质

在 CLI 和 HTTP API 中,图片默认以标准画质发送。OpenClaw 会自动以原图画质发送图片。视频默认以普通画质发送。

选择发送画质

发送接收方可获得的副本
图片,standard(默认)压缩后的 standard 与 thumbnail;无原图
图片,original全分辨率 original,另含 standard 与 thumbnail
视频,normal(默认)处理后的播放版与缩略图
视频,original播放版与缩略图,另含未修改的原始视频
文件附件未修改的源文件字节

图片: 原图画质会保留 JPEG 源文件的字节。PNG、GIF 和 WebP 源文件将以全分辨率转换为 JPEG。生成的高清与缩略图副本,其长边起始分别为 640 与 160 像素;处理时会先降低 JPEG 质量,再缩小尺寸,直至每个副本都不超过 65,520 字节。小图不会被放大。

图片源文件的大小上限为 26,214,383 字节。JPEG 允许 6400 万像素,每条边最多 8,192 像素;较大的 RGB 与灰度 JPEG 会以降低分辨率的方式解码,用于生成预览。其他格式允许 16,777,216 像素。若图片更大,或需要保留非 JPEG 的原始字节,请作为文件附件发送。

视频: MOV、MP4、3GP、3G2 和 MJ2 源文件最大允许 512 MiB。播放版使用 H.264 Main 配置,长边最多 720 像素,帧率最高 30 fps;若存在音频,则使用 AAC 编码。处理过程绝不会缩短视频时长。容器格式能否支持,取决于其所用的编解码器。

从 CLI 发送

  1. 发送压缩后的图片,或同时附带全分辨率原图:

    Terminal window
    wx messages send filehelper --image ./photo.jpg \
    --idempotency-key photo-standard --wait 3600
    wx messages send filehelper --image ./photo.jpg --image-quality original \
    --idempotency-key photo-original --wait 3600
  2. 选择视频画质:

    Terminal window
    wx messages send filehelper --video ./clip.mp4 --video-quality normal \
    --idempotency-key clip-normal --wait 3600
    wx messages send filehelper --video ./clip.mp4 --video-quality original \
    --idempotency-key clip-original --wait 3600
  3. 使用 wx --json jobs get JOB_ID 查看返回的任务。发送成功后,结果中会包含以下字段:

    {"state":"accepted","result":{"uploadReadbackVerified":true}}

    图片任务还会在 result 中报告 imagePreparation.originalAdvertised 与 imagePreparation.sourcePreserved。

HTTP API 与 SDK

先上传源文件,然后向 POST /sends 提交请求,并附带 Idempotency-Key 请求头:

{
"threadId": "filehelper",
"kind": "image",
"sourceId": "SOURCE_ID",
"imageQuality": "original"
}

标准图片请省略 imageQuality。发送视频时,请使用 kind: "video",并可选择传入 videoQuality: "original"。SDK 的 sendMedia 接受相同的字段。

可选的 standardSourceId 与 thumbnailSourceId 可接收单独上传的 JPEG 副本,每个不超过 65,520 字节。省略的副本将自动生成。

OpenClaw

普通消息工具的 media 字段会自动以原图画质发送图片。JPEG 保留其源文件字节;其他受支持的图片格式会转换为全分辨率 JPEG。若需以文件附件形式原样发送字节,请使用 asDocument: true。

发送原始视频时,请添加:

{
"channelData": {
"agent-wechat": { "videoQuality": "original" }
}
}

请将 mediaMaxMb 设置得足够大,以容纳源文件。视频画质选项不能与文档模式同时使用。

下载副本

  1. 请求 best(默认值)或消息中声明的某个版本:

    Terminal window
    wx messages media CHAT_ID IMAGE_ID --quality standard --output ./standard.jpg
    wx messages media CHAT_ID IMAGE_ID --quality original --output ./original.jpg

    --cached-only 会禁止下载。若本地没有缓存副本,则报告 state: "not_cached"。

  2. 检查返回资源中的 state 与 actualVariant。请求原图时,不能用预览图替代,也无法恢复发送前已被去除的细节。有关 API 与 SDK 的下载步骤,请参见媒体。在 OpenClaw 中,若消息提供了原图,请使用 wechat_media 并传入 quality: "original"。