76 lines
2.8 KiB
Markdown
76 lines
2.8 KiB
Markdown
# 多媒体输入（图片 / 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/分辨率/质量，或回退更少帧）
|
||
- 使用临时目录并确保清理；并发下避免落盘文件名冲突
|
||
|