展开本页目录
开始前准备什么
- 保存脱敏后的状态、错误字段和请求协议，不保存 Key。
- 准备小型无隐私测试图片与支持视觉输入的准确型号。
- 把图片下载、解码和模型识别分成三项检查。
- 确认协议
- 检查图片字节
- 检查访问地址
- 修复 content 字段
- 发一次小图验证
下载图片输入修复夹具
3 组完整请求前后对照；示意错误与一像素数据。
下载离线检查器
无网络请求，检查基本结构和固定夹具。
三种协议，图片对象各不相同
先定位 SDK 真正发送的端点，再看 content。不要把 Responses 的 input_image 对象直接塞进 Chat；原生 Messages 也不是同一个对象结构。
| 协议 | 文本类型 | 图片字段 |
|---|---|---|
| Chat /v1/chat/completions | text | type=image_url，image_url={url: ...} |
| Responses /v1/responses | input_text | type=input_image，image_url 是字符串 |
| Messages /v1/messages | text | type=image，source={type:base64,media_type,data} |
- 协议
- Chat /v1/chat/completions
- 文本类型
- text
- 图片字段
- type=image_url，image_url={url: ...}
- 协议
- Responses /v1/responses
- 文本类型
- input_text
- 图片字段
- type=input_image，image_url 是字符串
- 协议
- Messages /v1/messages
- 文本类型
- text
- 图片字段
- type=image，source={type:base64,media_type,data}
本地文件路径：修复前后完整形状
上面的错误文字与 <...> 为说明，不是已捕获的 apizt 错误，也不能直接发请求。下载文件含完整的一像素 data URL，专门检验请求形状；它不是有意义的识别测试。读取本地图片后编码真实字节，不把文件名或 HTML 转成 Base64 充数。
示意：Chat 图片部分修复
json
{
"before": {"type":"image_url","image_url":{"url":"file:///Users/demo/photo.png"}},
"illustrativeError": {"error":{"code":"invalid_image_url","message":"Image URL must be an accessible URL or a supported data URL."}},
"after": {"type":"image_url","image_url":{"url":"data:image/png;base64,<实际PNG字节的Base64>"}}
}三组独立问题与修复
| 修复前 | 问题 | 修复后 |
|---|---|---|
| file:///Users/demo/photo.png | 上游不能访问用户电脑 | 客户端读取字节，构造完整 data URL |
| 只有 iVBOR... Base64 文本 | 没有 scheme、MIME 与 base64 标识 | data:image/png;base64, 加实际编码内容 |
| Chat 请求中 type=input_image | 协议对象混用 | 改为 image_url 对象，或完整切换 Responses 请求 |
- 修复前
- file:///Users/demo/photo.png
- 问题
- 上游不能访问用户电脑
- 修复后
- 客户端读取字节，构造完整 data URL
- 修复前
- 只有 iVBOR... Base64 文本
- 问题
- 没有 scheme、MIME 与 base64 标识
- 修复后
- data:image/png;base64, 加实际编码内容
- 修复前
- Chat 请求中 type=input_image
- 问题
- 协议对象混用
- 修复后
- 改为 image_url 对象，或完整切换 Responses 请求
本站绘制的内容说明图：修复来源、MIME 与协议对象是不同操作；此页 before/after fixture 不会自动上传或请求模型。
HTTPS 地址可打开，还要检查返回字节
- 图片链接应直接返回正确图片字节；相册页面、登录页、403 HTML 或重定向页不能当图片。
- 确认 URL 有效期覆盖请求期间，并且上游能访问；你本机可打开不证明模型服务器可读取。
- 短期签名地址和私有文件不贴到公开日志。发送 data URL 时也不要记录完整图片字节。
- PNG/JPEG/WebP 等格式、文件大小和像素限制，以具体型号与通道为准。
下载三组夹具，只在本地检查
检查器验证 before 的预期问题和 after 的基本形状，不下载 HTTPS 文件、不执行模型识别，也不覆盖所有供应商字段。18 项检查中的图片相关部分为 3 组前后检查。HTTP 200 后仍需人工核对识别结果。
下载检查器与对应 JSON 到同一目录
bash
python3 check-request-fixtures.py image-url-fixtures.json修复之后验证什么
| 层次 | 通过条件 | 后续 |
|---|---|---|
| 文件 | 能解码为实际图片 | 核对 MIME、尺寸和真实内容 |
| 协议 | 端点与 content 对象一致 | 先用小图，不叠加工具 |
| 网络 | 上游实际收到图片 | URL 方案和 data URL 分开查 |
| 识别 | 答案对应画面，没有虚构 | 按固定事实人工验收 |
| 费用 | 同一请求的用量与账单 | 未知状态先回查，避免重复请求 |
- 层次
- 文件
- 通过条件
- 能解码为实际图片
- 后续
- 核对 MIME、尺寸和真实内容
- 层次
- 协议
- 通过条件
- 端点与 content 对象一致
- 后续
- 先用小图，不叠加工具
- 层次
- 网络
- 通过条件
- 上游实际收到图片
- 后续
- URL 方案和 data URL 分开查
- 层次
- 识别
- 通过条件
- 答案对应画面，没有虚构
- 后续
- 按固定事实人工验收
- 层次
- 费用
- 通过条件
- 同一请求的用量与账单
- 后续
- 未知状态先回查，避免重复请求
本站绘制的内容说明图：协议结构通过仍不证明模型看到了图片；URL 与 data URL 两种方式分别核验。
怎样确认已经完成
- 图片字节、MIME 与 data URL 前缀一致。
- SDK 实际端点与图片对象一致。
- 目标型号确实支持视觉，答复对应真实图片。
- 错误说明与真实日志明确区分。
常见问题
图片在浏览器可以打开，为什么 API 还是报错？
可能是需要登录、地址过期、上游访问受限或返回 HTML。检查实际状态和图片字节，并在目标请求链路验证。
Base64 一定比 URL 更好吗？
它省去上游下载地址的步骤，但增加请求体积；仍受格式、大小、像素和型号限制。
换成 data URL 就能用所有模型识别吗？
不能。还需支持视觉的准确型号和对应通道权限。