kiro.rs/docs/media.md

多媒体输入（图片 / GIF / 视频）

本项目在 Anthropic → Kiro 的协议转换过程中，会把 messages[].content 里的 image 内容块转换为上游 Kiro API 的 images[] 字段。

为避免上游对“大请求体/异常输入”返回 400 Improperly formed request，对 GIF 做了专门处理（抽帧→静态图）。

图片（静态）

当前支持的静态图片 source.media_type：

• image/jpeg
• image/png
• image/webp

处理策略：

• 读取尺寸后按配置做等比缩放（长边/像素上限）
• 保持原格式重编码（仅在需要缩放时）

GIF（动图）

为什么不能直接透传 GIF

GIF 常见特征是「分辨率不大但字节体积巨大」（多帧 + 调色板 + 压缩特性），如果把整段 GIF base64 原样塞进上游请求体，极易触发上游的请求体大小/校验限制（表现为 400 Improperly formed request 这类兜底错误）。

当前实现：抽帧输出多张静态图

当检测到 source.media_type=image/gif 时，会：

1. 解码 GIF，计算总时长与源帧数
2. 按时间轴采样（见下方采样策略）
3. 对被选中的帧按同样的缩放规则处理，并重编码为静态 jpeg
4. 将这些帧按时间顺序写入上游请求的 images[]

采样策略（固定上限，按时长自适应）

约束：

• 总输出帧数 <= 20
• 采样频率 <= 5 fps

规则（等价描述）：

• fps = min(5, floor(20 / ceil(duration_seconds)))
• interval_ms = 1000 / fps
• 若 duration_seconds 很大导致 fps=0，则按 interval_ms = ceil(duration_ms / 20) 做均匀采样

例子：

• 8 秒 GIF：floor(20/8)=2 → 2 fps → interval=500ms → 最多约 16 张
• 4 秒 GIF：floor(20/4)=5 → 5 fps → interval=200ms → 最多 20 张

视频（mp4 / mov 等）

当前状态：未实现。

说明：

• Anthropic 的 image 内容块规范里通常不会发送 video/*，因此本项目当前也不会把 video/mp4、video/quicktime 等媒体类型转换成上游 images[]（等价于不支持/忽略）。

规划方案（记录，暂不实现）

如果未来需要支持“视频 → 多张静态图”的输入，推荐方案是引入视频解码能力（通常依赖 ffmpeg/ffprobe）：

1. ffprobe 读取视频时长（毫秒）
2. 复用 GIF 的采样策略计算 interval_ms，并限制 <=20 帧、<=5fps
3. ffmpeg 按时间点抽帧（导出 jpeg/webp）
4. 每帧按现有缩放规则处理后 base64 化，写入 images[]

建议配套的安全/稳定性约束（避免 DoS 与请求体爆炸）：

• 限制输入视频最大字节数与最大时长（超限直接 400）
• 限制抽帧后总输出图片字节数（超限则降低 fps/分辨率/质量，或回退更少帧）
• 使用临时目录并确保清理；并发下避免落盘文件名冲突