多模态大模型API怎么传图片和文件？从输入格式到Token、权限与结果校验的实用指南

多模态大模型API的输入通常由文本和视觉或文件内容组成。不同服务的字段名称、支持格式和文件处理方式并不完全相同，因此接入时不能只复制一个请求示例，还要先核对目标模型的接口文档、权限要求和限制条件。

一、图片输入的三种常见方式

1. 图片URL

如果接口支持图片URL，可以在消息内容中传入图片地址。服务端需要能够访问该地址，私有对象存储通常要使用带有效期的签名URL。应确认接口是否允许外部URL、是否支持HTTPS，以及URL在请求处理期间是否保持有效。不要把包含长期密钥的地址直接写入请求。

2. Base64编码

Base64适合图片已经在应用服务器内存中，或暂时没有可访问URL的场景。请求一般会把媒体类型和编码后的数据放在数据URL中，例如：data:image/png;base64,编码后的内容。编码会增加请求体体积，图片过大时可能触发网关或服务端限制，因此上传前应按业务需要压缩和缩放，并保留原图用于追溯。

3. 独立文件上传接口

部分平台要求先调用文件上传接口，再在模型请求中引用文件标识。这种方式适合PDF、较大图片或需要多次复用的文件，但通常涉及文件用途、权限、保存期限和可用模型范围。上传成功不等于模型一定支持解析该文件，仍需检查模型与文件类型的兼容性。

二、先核对限制，再设计请求

至少应记录以下限制：允许的MIME类型和扩展名、单文件大小、单次请求大小、图片宽高或分辨率、PDF页数、一次可提交的文件数量、上下文长度、超时时间，以及是否要求特定权限。不同模型、接口版本和账号配置可能采用不同限制，不能把某个平台的数值当成通用标准。

图片与文本通常都会占用模型上下文，视觉输入的计费或Token计算也可能按图片尺寸、细节级别、页数或服务规则变化，不能简单写成“一张图固定多少Token”。工程上应以目标服务返回的用量字段、账单明细或官方计算规则为准，并为长文本、高清图片和多页文件设置预算。

三、请求体与超时处理

一个通用的消息结构可以表达为：{"model":"目标模型","input":[{"role":"user","content":[{"type":"text","text":"请提取发票号码、日期和金额，并返回JSON"},{"type":"image_url","image_url":{"url":"图片地址"}}]}]}。实际字段可能是messages、input、file_id或其他名称，必须按目标接口替换。

发送时设置正确的Content-Type和认证请求头。JSON请求通常使用application/json；独立文件上传常见multipart/form-data，但不要手动固定 multipart 的 boundary，应交给HTTP客户端生成。客户端还应设置连接超时、读取超时和总超时，并对429、5xx、无效文件、权限不足、请求体过大等错误分别记录和处理。重试时要采用退避策略，避免对非幂等操作造成重复上传或重复执行。

四、三个可落地的使用场景

1. 产品截图取数：同时发送截图和字段清单，要求模型输出字段名、值和置信说明；对价格、型号等关键字段再用正则或业务字典校验。
2. 发票转结构化JSON：上传PDF或图片后要求输出发票号码、日期、金额和税额。先检查返回内容能否被JSON解析，再验证日期格式、金额类型和税额关系。
3. 流程图转节点清单：要求输出节点、连线、分支条件和无法识别的区域。对复杂箭头、低清文字和重叠节点保留人工复核环节。

五、结果验收不能只看HTTP状态码

HTTP 200只表示请求在传输层或接口层成功，不代表内容正确。建议检查返回结构、finish状态、用量信息和安全过滤结果；对模型生成的JSON使用严格Schema校验，对表格检查行列数和必填字段，对金额、日期、编号等关键值执行格式与范围验证。图片模糊、手写内容、复杂表格和遮挡区域都可能导致识别错误，无法承诺完全准确。生产系统应保存原始文件、请求标识、模型输出和修正记录，并把需要确认的结果交给人工复核。