多模态 API 接入实战：看图接口的模型名、Token 计费与多模型路由
摘要：视觉大模型 API 已经普及，但"能调通"和"能稳定跑在生产上"之间隔着不少细节：模型名拼错直接 400、图片按视觉 Token 折算计费、多模型怎么路由与降级、实验模型误入生产默认路由。这篇文章以 DeepSeek 看图 API 等为例，把从零接入到生产可用的工程细节讲透。
一、看图 API 的第一步：请求格式与模型名
多数厂商都提供 OpenAI 兼容接口，看图请求的核心是把图片放进 image_url。一个最小可用的请求长这样：
from openai import OpenAI
client = OpenAI(base_url="https://api.example.com/v1", api_key="sk-...")
resp = client.chat.completions.create(
model="deepseek-chat", # 必须使用支持视觉的模型名
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "这张截图里的报错是什么原因？"},
{"type": "image_url", "image_url": {"url": "https://example.com/err.png"}},
],
}],
)
print(resp.choices0.message.content)
最容易踩的三个坑：
• 模型名写错：视觉能力通常挂在特定模型名上（有的厂商叫 *-vl，有的叫 *-vision，有的是同一模型名开视觉开关）。用不支持视觉的模型名传图，会返回 400 invalid model 或 model not found；
• base64 必须带 MIME：本地图片转 base64 时要用 data:image/jpeg;base64,xxx 的形式，漏掉 data:image/jpeg;base64, 前缀，接口会当成非法 URL 报错；
• URL 需要公网可达：内网地址、带鉴权的图片 URL 会拉取失败，生产环境建议统一走"先上传对象存储、再传公网 URL"的流程。
二、Token 计费：图片是怎么折算的
看图接口按"视觉 Token"计费，规则各家略有差异，常见做法是按分辨率阶梯折算，而不是按图片文件大小：
• 低分辨率一图折算为固定档位（如 384 / 512 Token 一档）；
• 高分辨率按分块计算（如把图切成多个 tile，每 tile 一档 Token），图越大越贵；
• 一次请求多张图 = 各图 Token 之和 + 文本 Token。
估算成本可以用一个简单公式：单次成本 ≈ Σ(每张图的视觉 Token) × 单价 + 输出 Token × 单价。想压成本，工程上有几个立竿见影的手段：
• 降采样：分析型任务把图缩到 1024px 以内，多数场景识别率不掉；
• 压缩转格式：PNG 转 JPEG、去掉透明通道，能明显减少体积（但注意：视觉 Token 按分辨率算，压缩文件体积不一定省钱，重点是降分辨率）；
• 限制张数：截图类任务一次最多 2~3 张，先做"选图"再"看图"；
• 结果缓存：同一图片指纹（内容 hash）的识别结果缓存，重复请求直接命中。
三、多模型调用的工程化：路由与容错
生产环境很少只接一家。统一网关 + 多模型路由是标准做法：
def chat_vision(prompt, images, prefer="cost"):
"""按策略选模型：cost=成本优先 / quality=质量优先 / fallback=主备"""
model = route_model(prefer, task="vision")
try:
return call(model, prompt, images)
except ProviderError as e:
if e.code in FINGERPRINT_TRIGGER_DOWNGRADE: # 错误码指纹命中
return call(fallback_model, prompt, images)
raise
三个关键点：
• 统一抽象层：所有厂商走同一套 OpenAI 兼容参数，切换模型只改一个模型名，业务代码不动；
• 路由策略：按能力路由（视觉任务只进视觉模型）、按成本路由（默认走便宜的，失败/超时降级到贵的）、主备降级（A 挂了自动切 B）；
• 错误码指纹：不同厂商的错误体格式差异很大，有的用 code=1214 这类数字码，有的用英文消息。把特征错误码做成指纹表，命中即可触发降级或告警，比盲试超时重试高效得多。示例：某厂商对不支持参数的请求返回 1214，路由层直接把它映射成"参数不兼容 → 切换兼容模型"，而不是重试同一个注定失败的请求。
四、企业接入的护栏：把实验模型挡在生产默认路由外
多模型时代最危险的不是调用失败，而是新模型悄悄进了默认路由。建议三件事：
• 白名单 + 灰度：默认路由只允许审批过的模型；新模型（尤其是匿名、实验性、社区命名的模型）默认禁入，先在灰度环境小流量跑观察稳定性和成本，再放量；
• 配额与成本上限：按业务线、按账号设每日 Token 配额和金额上限，超限自动降级到廉价模型或熔断；
• 观测与审计：记录每次请求的模型名、Token 消耗、错误码、耗时，按模型/业务线聚合，既能定位成本大头，也能在异常路由时快速回溯。
五、总结：生产接入检查清单
-
模型名确认支持视觉，传图前先跑一次最小用例；
-
base64 带 MIME 前缀，图片 URL 公网可达；
-
算清视觉 Token 计费，做降采样与缓存控成本；
-
统一网关 + 能力/成本/主备路由；
-
错误码指纹表驱动降级，不盲试重试；
-
新模型白名单灰度，默认路由不含实验模型；
-
配额上限 + 全量日志审计。
结语：看图接口的接入门槛并不高，难的是把它做成"生产可用"------模型名、计费、路由、护栏，每一环都有细节。把上面清单走一遍，你的多模态调用大概率能少踩 80% 的坑。