两种传法：URL 和 base64
图片有两种传法：给一个公网可访问的 URL，或者把图片编码成 base64 塞进 data URL。URL 传输量小、请求快，但要求图片能被上游访问到，内网图片和带签名的临时链接经常失效。base64 不依赖外网，体积会涨三分之一左右，请求体容易超过网关限制。
签名 URL 还有过期问题：链接生成时有效，模型真正去取的时候已经 403。批量任务里尤其明显，一批图放到队列里排半小时，前面的链接就死了。
临时图片、本地文件用 base64；已经在 CDN 上的公开图片用 URL，能省带宽也省解析时间。
base64 的体积约为原图的 1.33 倍，一张 3MB 的照片编码后 4MB，再算上 JSON 转义，请求体可能到 5MB 以上。多数网关对这个量级还算宽容，移动网络上传会很慢。
一个能跑的图片请求
import base64
import requests
def data_url(path: str, mime: str = "image/jpeg") -> str:
with open(path, "rb") as f:
return f"data:{mime};base64," + base64.b64encode(f.read()).decode()
resp = requests.post(
"https://ai.idcidiot.com/v1/chat/completions",
headers={"Authorization": "Bearer sk-..."},
json={
"model": "gemini-3.8-flash",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "这张图里的表格有几行？只回数字。"},
{"type": "image_url", "image_url": {"url": data_url("table.jpg"), "detail": "high"}},
],
}],
"max_tokens": 50,
},
timeout=120,
)
print(resp.json()["choices"][0]["message"]["content"])URL 写法把 image_url.url 换成 https://... 即可，其余不变。detail 设成 low 会降采样，小字和表格线容易糊掉，识别任务一般用 high。
格式与体积
常见支持 png、jpeg、webp，gif 是否按多帧处理看厂商。上传前把长边压到 1500 像素上下、单张控制在 1MB 以内，大多数识别任务够用。
体积上限、像素上限、支持格式以官方文档为准，超限一般返回 400，报错里会写清楚是哪个字段。压缩用 Pillow 一行就够：img.thumbnail((1500, 1500))。
动图别指望模型逐帧理解，抽第一帧或者转成三张静图更可靠。带透明通道的 png 在部分模型上会被填成白底，深色文字可能看不清，传之前先合到白底上。压缩完体积还是大，就拆成两张图分别传，比一次传一张巨图稳。
文件不等于图片
PDF、Excel 这类文件并不是所有模型都能直接吃。Claude 与 Gemini 支持直接传 PDF；OpenAI 的 chat/completions 不收 PDF，需要先抽文本或者用它的文件接口。传之前先确认模型支持哪些输入类型，模型页会列出 input_modalities。
一份 200 页的 PDF 直接塞进去，token 消耗可能比你想的高一个数量级。先抽目录和相关章节，再决定要不要整份传。
扫描版 PDF 没有文字层，抽文本抽出来是空的，这类只能按图片处理，成本按页数走。
成本怎么算
图片按 token 计费，换算规则跟分辨率、厂商有关。gemini-3.8-flash 在 Gemini Antigravity 分组输入 0.975 美元每百万 token，一张折合 1000 token 的图约 0.001 美元；一天 500 张不到 0.5 美元。真正贵的是把整本扫描件当图片传。
账单异常时先看 prompt_tokens 有没有暴涨，再回头看是不是图片尺寸失控。
动手前把图片数量、单张 token、调用次数乘一遍。OCR 预处理之后文本可能只剩几百 token，比直接传图便宜一个量级，识别率也更稳。
常见失败
- 400：data URL 少了
data:image/jpeg;base64,前缀，或者 base64 里混进了换行。 - 400 或 415：格式不支持，或者文件是 webp 改了后缀。上传前用
file命令确认真实格式，比看后缀可靠。 - 超时：单张图太大，先压缩再传。
- 答非所问：
detail设成了low，或者图片本身分辨率太低。 - 多图对不上号：一次传多张图时，给每张配一句文字说明，模型才知道哪张是正面、哪张是背面。
模型清单见 模型总览，gemini-3.8-flash 的上下文和输出上限在 模型页，价格对照在 定价页，更多接入细节可以翻 文章列表。先拿十张真实图片跑一遍，比对着文档猜格式快。