多模态模型API调用完全解析

文本模型通常是“传入字符串返回字符串”换成图片、语音和视频调用链就多了文件传输、媒体编码、任务调度和结果解析。图片是否转 Base64、视频为何先返回任务 ID、语音结果是 JSON 还是二进制流这些问题不能靠增加几个参数解决。这篇文章不深挖 SDK 代码而是讲清多模态协议背后的处理链路图片识别如何变成文字文字如何生成图片语音和视频又该怎样传入、等待和解析。一、先纠正一个误解多模态不是“文件版文本接口”文本请求的核心对象是Token。用户输入一句话Tokenizer把它切成Token模型在统一的向量空间里推理再由文本解码器逐Token生成答案。图片、音频和视频进入模型前必须先经过各自的预处理与编码过程。这几种输入最后都可能被映射成模型能处理的向量或Token但计费方法、长度上限和信息损失并不相同。模态进入模型前的典型处理主要成本变量常见输出文本分词、Token化输入与输出Token数文本、JSON、工具调用图片解码、缩放、切块、视觉编码图片数量、尺寸、细节等级文本、JSON、图片音频解码、重采样、分帧、声学编码时长、采样率、声道、音频Token转写文本、时间戳、音频流视频解码、抽帧、时序建模、音轨处理时长、帧率、分辨率、音轨摘要文本、时间轴、视频文件关键洞察多模态调用要先区分“理解”和“生成”。理解任务把媒体变成文本或结构化信息生成任务把指令变成二进制媒体。两者不能共用一套只读取message.content的解析代码。二、统一协议的核心消息里不再只有字符串不同厂商的字段名不一样但设计思路越来越接近一条消息由多个“内容块”组成每个内容块用type或MIME类型说明自己是什么。下面不是某家厂商的原始协议而是一层适合业务系统使用的统一抽象{ task: understand | generate, model: provider/model-id, messages: [ { role: user, content: [ {type: text, text: 识别图片中的商品和价格}, { type: image, source: { kind: url | base64 | file_id, value: ..., mime_type: image/jpeg }, detail: auto } ] } ], generation_config: {}, output: { modalities: [text], format: json }}这层统一协议解决三件事业务代码不用到处判断OpenAI、Claude还是Gemini。文本、图片、音频和视频都能按内容块顺序组合。输入媒体、生成参数和期望输出被分开后续换模型时不至于把业务参数与厂商字段绑死。2.1 为什么内容块的顺序仍然重要多模态模型会结合文本和媒体共同理解问题。虽然不少模型能处理任意顺序实际调用中仍建议采用清晰、固定的排列方式单图问答 图片 → 针对这张图的问题多图对比 图片A → 标签A → 图片B → 标签B → 对比要求图文混排文档 文字说明 → 对应图片 → 下一段文字 → 下一张图片如果一次传入五张图片只在最后写一句“分析一下”模型可能知道每张图的内容却不知道业务上要比较什么。协议能传进去不代表提示词已经把关系说清楚。2.2 MIME类型不是可有可无的备注image/jpeg、audio/wav、video/mp4告诉服务端应该用什么解码器处理数据。扩展名写着.jpg实际内容却是WebP轻则请求失败重则在不同环境得到不同结果。生产系统应同时校验文件头与MIME类型是否一致文件大小、像素、时长和编码是否在模型限制内Base64解码后的真实体积是否超限URL是否可访问是否会过期是否可能指向内网地址。三、img2text图片是怎样变成文字的img2text不只是OCR。根据提示词不同同一张图片可以触发完全不同的任务。任务模型需要做什么适合的输出OCR读取图片中的可见文字纯文本、段落、带坐标文本块图片描述识别主体、环境、动作和关系自然语言票据提取找到金额、日期、商户、税号JSON图表理解识别坐标、图例、趋势和异常JSON加结论视觉问答只回答与问题相关的信息短文本或结构化字段目标定位返回物体类别和位置边界框、点坐标、置信度现代视觉语言模型通常会把图片缩放或切成图块再编码成视觉Token与文本Token一同进入模型。OCR可能是模型能力的一部分但不是所有图片理解都先生成一份完整OCR文本。处理照片中的空间关系、商品外观或图表趋势时单纯OCR远远不够。3.1 OpenAI图片理解协议OpenAI Responses API把文字和图片放进同一个content数组。图片可通过URL、Base64 Data URL或Files API产生的file_id传入。官方文档也说明多张图片会分别计入输入成本。OpenAI图片与视觉文档{ model: vision-capable-model, input: [ { role: user, content: [ {type: input_text, text: 提取图片中的商品名、数量和金额返回JSON}, { type: input_image, image_url: https://example.com/receipt.jpg, detail: high } ] } ]}这里最值得关注的参数不是temperature而是媒体本身参数作用选择建议image_url公开URL或Base64 Data URL临时单图可用敏感图不要放公开URLfile_id引用已上传文件大文件、复用文件、多轮任务更合适detail控制视觉处理精度快速分类用低档小字、表格、界面截图用高档或原图档图片数量一次请求中的图片块数量多图能比较但成本和歧义同步增加图片尺寸影响切块、视觉Token和识别精度保留有效细节先裁掉无关大背景提示词定义识别目标和输出格式不要只写“识别图片”应写清字段与失败处理OpenAI当前文档中的detail可按模型支持设置为low、high、original或auto。不同模型会采用不同的缩放和切块规则因此不能把某个固定分辨率公式当成所有模型的标准。OpenAI视觉细节等级说明3.2 img2text的输出不要只取第一段文字多模态响应往往是一个内容块数组里面可能同时出现文本、拒答、工具调用、引用或错误信息。稳妥的解析顺序是第一步检查HTTP状态和请求ID第二步确认顶层任务状态是否完成第三步遍历output/content内容块第四步按type分别收集text、tool_call、refusal、error第五步如果要求JSON再做Schema校验第六步记录usage、模型版本和媒体元数据有SDK提供output_text之类的便捷字段时可以用于简单问答。生产系统仍应保留原始响应因为一旦模型返回多个内容块单一字符串会丢掉上下文。3.3 结构化提取必须允许“不确定”票据、证件、医学影像和工业质检最怕模型“补全”看不清的内容。输出协议应显式保留空值、证据和置信信息{ merchant: {value: 示例商店, evidence: 图片顶部, status: readable}, total: {value: 128.50, currency: CNY, status: readable}, invoice_code: {value: null, status: unclear}, warnings: [右下角存在反光部分字符无法确认]}模型给出的“置信度”不一定经过统计校准不能直接当成真实概率。更可靠的做法是保存证据位置对关键字段做规则校验并在金额、身份、医疗等高风险场景加入人工复核。四、text2img文字生成图片的协议怎样设计图片理解通常是“媒体输入、文本输出”图片生成正好相反。请求仍是JSON响应却可能包含Base64图片、临时URL或图片内容块。4.1 先选单次生成还是对话式生成OpenAI提供两条主要路径Image API适合一次提示词生成或编辑一张图片Responses API中的图片生成工具适合多轮对话、连续修改和把图片放回上下文继续处理。需求推荐协议一句话生成海报独立图片生成端点上传商品图后更换背景图片编辑端点“再亮一点、人物往左移”连续修改对话API加图片生成工具业务系统批量出图异步队列封装图片端点不要因为Responses API能生成图片就把所有出图任务都塞进对话接口。一次性生成走专用端点协议更简单成本也更容易核算。4.2 text2img请求中真正重要的参数{ model: image-generation-model, prompt: 一张适合公众号封面的现代科技插画……, size: landscape, quality: medium, background: opaque, output_format: png, n: 1}参数类别常见字段要解决的问题内容描述prompt画什么、主体之间是什么关系构图size、aspect_ratio横版、竖版、方图以及留白位置质量quality、分辨率预览图还是最终成片外观风格、光线、色彩、镜头让结果稳定接近品牌要求背景background透明底还是不透明底文件output_format、压缩质量PNG、JPEG、WebP及体积控制数量n一次生成多少候选图编辑输入输入图、遮罩、参考图修改哪里、保留什么字段是否支持、枚举有哪些取决于模型和端点。统一协议可以保留这些概念适配层只能发送目标模型真正支持的字段不能把OpenAI的quality直接照搬给所有厂商。4.3 提示词本身也应该协议化“帮我根据问题生成一张图片”太宽泛。可以把提示词拆成业务字段再由系统拼成最终提示词主题多模态模型如何处理图片、语音和视频用途微信公众号封面主体中心是一枚多模态模型芯片关系图片、麦克风、视频帧从左侧进入文字与媒体从右侧输出构图横版2.35:1中心主体左右留出标题区风格现代科技插画简洁不写实配色白底、深蓝主色、橙色高光文字不在画面中生成小字限制不要复杂背景不要品牌Logo不要水印这种结构方便做模板、版本管理和A/B测试。它也能减少一个常见问题用户改了画面比例系统却把整段提示词全部重写导致人物、风格和色彩一起漂移。4.4 图片结果如何解析和保存图片生成响应常见三种形态返回形态解析方式注意事项Base64解码为字节后写入文件或对象存储Base64体积约比原始二进制更大不要长期放数据库临时URL后端下载后转存到自己的存储URL可能过期不应直接作为永久资产地址图片内容块遍历响应找到图片类型并读取数据或文件ID同一响应可能还带文本说明和修改后的提示词落盘时至少保存这些元数据asset_id业务侧唯一IDrequest_id模型服务请求IDmodel实际使用的模型与版本prompt_version提示词模板版本mime_type真实文件类型width / height实际输出尺寸sha256内容校验值storage_uri自己的对象存储地址created_at生成时间把“模型返回成功”直接等同于“图片资产可用”很危险。下载失败、Base64损坏、扩展名错误、内容审核未通过都应该在资产入库前处理。五、语音协议转写、合成和实时对话是三套逻辑音频场景经常被统称为“语音模型”实际至少包含三类任务任务输入输出典型协议speech2text音频文件或音频流文本、分段、时间戳、说话人文件上传或实时事件流text2speech文本、音色、语气指令MP3、WAV、PCM等音频JSON请求加二进制响应speech2speech实时语音、上下文、工具结果实时语音与事件WebRTC或WebSocket5.1 speech2text上传的不只是一个MP3离线转写一般使用multipart/form-data上传文件同时提交模型和转写参数。OpenAI语音转文字文档file音频二进制model转写模型language已知语言可减少误判prompt专有名词或上下文提示不等同于普通聊天Promptresponse_formattext、json、verbose_json或带说话人的JSONtimestamp_granularities句段级或词级时间戳取决于模型支持chunking_strategy长音频如何切分known_speaker_references已知说话人的参考音频取决于模型支持纯文本适合字幕草稿会议纪要、客服质检和播客剪辑更需要结构化结果{ text: 完整转写文本, segments: [ {start: 0.0, end: 4.2, speaker: speaker_0, text: 大家好会议开始。} ], language: zh, duration: 1842.6}长音频不能随便按固定字节切开。切点落在一个词中间会损失上下文多人会议还会破坏说话人连续性。生产方案通常按静音区间或模型推荐的切块策略分段并保留少量重叠再在结果层去重拼接。5.2 text2speech返回的是媒体流语音合成请求通常包含input、voice、instructions和response_format。OpenAI官方示例支持通过自然语言控制语气并可把音频作为流返回。OpenAI文字转语音文档参数作用常见问题input要朗读的文本超长文本应按语义分段避免切断句子voice音色或声音ID需记录版本避免后续音色变化instructions语气、速度、情绪、停顿要求不同模型的可控程度不同response_formatMP3、WAV、PCM等播放端必须知道采样率、位深、声道speed语速控制并非所有模型都支持MP3适合下载和存储PCM省去解码步骤适合低延迟播放但体积大而且必须额外约定采样率、声道数和采样位深。只返回一段PCM字节却不返回音频格式元数据调用方很难正确播放。5.3 实时语音解析的是事件不是完整文件实时语音通常通过WebRTC或WebSocket交换数据。客户端持续发送音频帧服务端持续返回事件输入事件 - 会话配置 - 音频缓冲区追加 - 音频缓冲区提交 - 文本消息 - 工具执行结果输出事件 - 语音活动开始/结束 - 转写增量 - 文本增量 - 音频增量 - 工具调用 - 响应完成或错误实时场景要额外关注VAD语音活动检测、打断、回声消除、抖动缓冲和断线重连。streamtrue只能说明要流式传输它没有定义每个事件的含义也不能替代会话状态机。六、视频协议理解与生成走两条完全不同的路6.1 视频理解模型看到的是时间序列视频理解常见两种实现平台原生接收视频文件由服务端完成解码、抽帧和音轨处理。业务侧先抽取关键帧与音频转写再把“图片序列时间戳文本”交给多模态模型。第二种方式更可控也更容易控制成本但会丢掉没有被抽到的瞬间。体育动作、设备故障、手势变化等高时序敏感任务需要更高帧率或专门的视频模型只抽每十秒一帧无法可靠判断中间发生了什么。视频理解的输入协议至少要保留sourceURL、Base64、file_id或对象存储引用mime_typevideo/mp4等真实类型start_time / end_time要分析的时间范围sampling抽帧策略或媒体分辨率等级audio_policy忽略、转写或保留音轨prompt要找的事件、人物、动作或摘要粒度output_schema摘要、时间轴、事件列表或字幕输出最好带时间范围而不是只返回一段总结{ summary: 顾客进入门店后在收银台停留随后离开。, events: [ {start: 12.4, end: 18.7, label: 进入门店, evidence: 入口摄像头}, {start: 42.1, end: 55.0, label: 停留在收银台, evidence: 人物位于柜台前} ]}6.2 text2video先创建任务再下载结果视频渲染耗时远高于文本和单张图片。OpenAI的视频生成协议是典型的异步任务模型调用POST /videos得到任务ID和初始状态随后轮询状态或等待Webhook完成后再从内容端点下载MP4。OpenAI视频生成文档1. 创建POST /videos 输入prompt、model、size、seconds、参考图等 输出id、status、progress2. 等待GET /videos/{id} 或 Webhook 状态queued、in_progress、completed、failed3. 获取GET /videos/{id}/content 输出视频二进制流视频生成参数主要分成四组参数组常见字段影响画面内容prompt、参考图、首尾帧主体、动作、镜头和一致性时空规格seconds、size、宽高比、帧率时长、清晰度、成本和渲染时间连续性扩展源视频、角色引用、前一任务ID角色与场景是否连贯任务控制幂等键、回调地址、超时、优先级重试是否重复扣费、结果如何回传视频Prompt比图片Prompt多一个时间维度。除了主体、风格和构图还要写清动作顺序、镜头运动、节奏、音效和结束状态0-2秒远景夜晚城市街道镜头缓慢前推2-6秒蓝色汽车从右向左驶过路面有雨水反光6-8秒镜头抬升露出远处霓虹招牌声音轻微雨声和远处车流声无对白限制不要切镜不要改变汽车颜色如果用户点了两次“生成”后端却没有幂等控制就可能创建两个昂贵的渲染任务。异步媒体任务应把client_request_id、供应商任务ID和业务资产ID分开保存并让Webhook处理具备幂等性。七、URL、Base64和文件ID应该怎样选传输方式优点缺点适用场景URL请求体小接入简单可能过期、鉴权困难、存在SSRF风险已在对象存储中的公开或签名资源Base64数据跟随请求单次调用完整体积膨胀耗内存不适合大媒体小图片、短音频、一次性调用file_id可复用适合多轮和大文件需要先上传并管理文件生命周期长文档、多轮图片分析、较大媒体直接二进制上传没有Base64膨胀协议常变为multipart网关需支持音频转写、图片编辑、视频参考文件一个实用的默认策略是小于数MB且只用一次Base64或multipart已经在云存储短期签名URL需要多轮复用先上传后续传file_id生成结果立即转存到自己的对象存储签名URL的有效期要覆盖排队和处理时间。视频任务排队数分钟后才读取参考图时五分钟有效的URL可能在模型真正处理前就失效。八、统一响应解析按类型分流不按接口猜结果文本时代常见的解析方式是读取某个固定路径例如choices[0].message.content。进入多模态后这种写法很快会失效。建议先把供应商响应转换成统一结果{ request_id: req_xxx, status: completed, outputs: [ {type: text, text: ...}, {type: image, mime_type: image/png, data_ref: asset_xxx}, {type: audio, mime_type: audio/wav, data_ref: asset_yyy} ], usage: { text_input_tokens: 120, image_input_units: 4, audio_seconds: 0, video_seconds: 0 }, warnings: []}解析器可按下面的分发规则工作响应信号处理方式Content-Type: application/json解析状态、内容块、usage与错误image/*校验图片头转存并生成资产记录audio/*或PCM流根据格式播放、转码或保存video/*流式写入对象存储避免整段读入内存statusqueued/in_progress保存任务状态稍后轮询或等待Webhookstatusfailed读取可重试属性和供应商错误码typerefusal作为业务可识别结果处理不要当网络异常重试8.1 多模态错误要分层传输层超时、断线、DNS失败、下载中断协议层MIME错误、Base64损坏、字段不支持、请求过大任务层排队失败、渲染失败、Webhook重复或乱序模型层无法识别、内容拒绝、输出不符合Schema资产层文件损坏、转存失败、URL过期、元数据不一致不是所有失败都适合自动重试。网络超时可以带幂等键重试内容审核拒绝不该换个请求ID无限重试视频任务状态查询超时也不能直接再创建一个新任务。九、多模态参数比文本参数多关注什么9.1 精度参数会同时改变成本和延迟文本里的temperature主要影响生成随机性。多模态里的detail、分辨率、时长和采样率会改变输入信息量通常也直接改变成本与延迟。图片数量 × 尺寸 × 细节等级音频时长 × 声道 × 采样设置视频时长 × 分辨率 × 帧率 × 音轨生成媒体输出尺寸 × 质量 × 数量或时长“全部使用最高质量”不是稳妥配置。商品粗分类不需要原图级视觉细节语音客服也不必保存无损音频视频Prompt调试阶段可先生成短片和低分辨率版本。9.2 模型参数不再完全通用temperature、top_p、max_output_tokens适用于很多文本输出但专用图片或视频生成模型未必支持。反过来background、voice、seconds也不能发给普通文本模型。适配层应维护一份能力表model_capabilities input_modalities支持哪些输入 output_modalities支持哪些输出 transportJSON、multipart、WebSocket或WebRTC sync_mode同步、流式或异步任务 supported_parameters允许的参数集合 limits文件大小、图片数量、音频时长、视频时长在请求发出前校验能力比等供应商返回unsupported_parameter更省时间。9.3 安全边界从Prompt扩展到了文件多模态输入会带来文本接口里不明显的风险图片可能包含提示注入文字诱导模型忽略系统规则URL可能访问内网、云元数据地址或超大文件图片解压后像素巨大形成解压炸弹文件EXIF可能泄露位置和设备信息语音涉及声纹、身份和同意问题生成图片、声音和视频涉及肖像、版权、水印及内容安全。因此媒体下载服务应设置域名与IP限制、体积上限、超时、重定向次数和内容扫描。敏感文件还要明确供应商的数据保留策略与访问权限。十、OpenAI、Claude、Gemini的协议怎样映射三家都采用“消息/内容块”思路但字段并不相同。统一概念OpenAI Responses APIClaude Messages APIGemini API消息集合inputmessagescontents或交互输入文本块input_texttextPart.text图片块input_imageimage图片Part内联数据Base64 Data URLsource.typebase64inline_dataURL引用image_urlsource.typeurlURL输入或对应文件引用文件引用file_idFiles API的file_idfile_data或Files API引用图片精度detail主要由图片尺寸和模型规则决定media_resolution等模型配置文本输出输出消息中的文本块content[].text候选内容中的文本Part图片生成Image API或Responses图片工具Messages API主要用于理解并返回文本原生图片模型返回图片Part视频生成/videos异步任务通常接入外部生成工具Veo或原生视频生成能力实时语音Realtime API依具体产品与工具能力Live APIClaude官方Messages API示例把图片写成{type:image,source:{...}}支持Base64、URL及文件引用等形式。Claude Messages文档Gemini把文本和媒体统一为Part小文件可放在inline_data中大文件或复用文件使用Files API。它的响应同样可能包含文本Part或图片Part因此也要按类型遍历。Gemini图片理解文档 Gemini图片生成文档关键洞察能统一的是业务概念不是供应商原始JSON。正确做法是在业务层定义text/image/audio/video再由适配器转换字段、过滤不支持的参数并解析各自响应。十一、生产系统推荐的四层设计第一层业务请求 定义任务、输入内容、期望输出和业务约束第二层媒体资产 负责上传、下载、转码、校验、签名URL和对象存储第三层模型适配 把统一内容块转换成OpenAI、Claude或Gemini协议第四层任务与结果 处理同步响应、流式事件、异步任务、Webhook和资产入库这四层分开后图片URL过期属于资产层模型字段变化属于适配层视频排队属于任务层。问题不会全部挤在一个call_model()函数里。上线前可以用下面这份清单做最后检查输入文件是否校验真实MIME、大小、像素和时长URL是否限制内网访问、重定向和下载体积是否区分文本、二进制流和异步任务响应是否遍历内容块而不是固定读取数组第一个元素结构化结果是否做JSON Schema校验并允许null视频和批量生成是否有幂等键、超时和Webhook验签生成媒体是否及时转存避免依赖供应商临时URL是否记录模型版本、请求ID、输入规格、usage和资产哈希高风险识别结果是否有规则校验或人工复核模型能力表和参数白名单是否随版本更新十二、总结文本API的主线是“输入Token输出Token”。多模态API多了两端工作输入端要处理文件传输、解码和媒体Token化输出端要处理内容块、二进制资产、实时事件或异步任务。真正稳定的多模态方案不是找到一个能接收所有文件的万能接口而是先回答三个问题这是理解任务还是生成任务输入媒体如何传输和计量输出是文本、文件、流还是任务ID这三点确定后图片识别、语音转写、图片生成和视频生成看似差异很大工程上却能落到同一套框架统一内容块、媒体资产层、模型适配器和按类型分流的结果解析器。模型会继续换字段也会继续变。把业务协议和厂商协议隔开才是多模态系统能长期维护的关键。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】