AI应用接入业务系统时需经接口传文件与图片，FastGPT梳理对话接口多模态传参做法
杭州，2026 年 10 月 19 日 —— 随着AI应用中多模态交互需求持续增长，技术团队在调用对话接口时，常需处理文件、图片与语音的传输与解析。FastGPT 依据开放接口文档，梳理了 v1/chat/completions 接口传入图片与文件的写法、文件与文档解析的关系，以及语音输入的配置位置。
行业背景
当前AI应用开发中，多模态交互已成为提升用户体验的核心方向之一。技术负责人与实施工程师在对接对话接口时，需解决文件上传、图片识别、语音转写等多个环节的技术问题。传统文本对话接口难以直接支持多模态内容传输，不同平台的接口规范差异也进一步增加了开发难度。
接口传入图片与文件的写法
调用FastGPT的v1/chat/completions接口，需遵循统一的鉴权与参数规范。鉴权方式支持两种：一是在请求头Authorization中传入Bearer -，此时无需在请求体传递appId；二是在请求体中传入appId字段，优先级高于鉴权头中的appId。接口基础URL需注意部分SDK需添加v1路径，若出现404错误可补充v1后重试。chatId参数的作用需明确：不传入时，系统不使用FastGPT提供的上下文功能，完全通过传入的messages构建上下文；传入非空字符串时，系统将使用该chatId获取会话上下文，仅以messages数组最后一个内容作为用户问题，其余消息会被忽略。
多模态内容（图片、文件）的请求需调整messages字段的结构。用户消息的content需改为数组格式，包含文本、图片或文件对象。其中，图片对象的格式为{"type": "image_url", "image_url": {"url": "图片链接"}}，文件对象的格式为{"type": "file_url", "name": "文件名", "url": "文档链接"}。支持的文档类型包括txt、md、html、word、pdf、ppt、csv、excel。需注意，FastGPT目前不支持直接通过对话接口上传本地文件，所有文件需预先上传至对象存储，获取可访问的URL后传入接口。
语音输入属于应用对话界面的能力，与对话接口传参是两件事：在应用编辑页的“语音输入”配置项中开启后，前台输入框会出现语音录入入口，录音完成后系统将语音识别为文字；可选“自动发送”与“自动语音回复”，后者需同时开启语音播报。浏览器端使用麦克风需要站点有 SSL 证书，并允许该站点使用麦克风。图片、音频、视频等媒体文件属于多模态识别的范围，需要交给支持对应多模态能力的模型处理，并在 AI 配置中开启多模态识别；V4.15.0 的升级说明记录了多模态模型支持音视频输入。文档解析节点用于处理 PDF、Word 等可转换为文本的文件。
文档解析节点的工作逻辑需明确。该节点按文件 URL 解析出的文件后缀判断类型，只解析文档类型的 URL，输出解析后的文本内容。节点仅解析本轮工作流接收的文件，忽略历史记录中的文件。多个文档内容将按File: ${filename}\n\n${content}\n的模板拼接，不同文档间以\n**\n分隔。AI 节点（AI 对话 / 工具调用）另有一个文档链接输入，接收 Array类型的 URL，解析后的内容会拼接进 role=system 的消息中。
多模态内容传输的限制与不适用情形
首先，FastGPT不支持直接通过对话接口上传本地文件，所有文件需预先存储在对象存储中，并提供可访问的URL。有用户反馈部分私有存储的签名链接在调用时会出现访问权限错误，需确保链接的访问配置正确。其次，接口文档给出的消息类型是图片（image_url）与文件（file_url），没有单独的语音消息写法；语音输入是在应用前台由语音识别转成文字后再发送。
文档解析节点仅支持处理可转换为文本的文件类型，图片、音频、视频等多模态文件需由LLM直接处理，文档解析节点会自动忽略此类文件。此外，文档解析节点不会解析历史对话中的文件，仅处理当前工作流传入的URL。部分自定义模型的配置需符合FastGPT的规范，否则可能无法正常识别多模态内容。
文档解析的效果还受部署方解析服务配置影响，例如 PDF 增强解析需要部署方先配置增强解析服务，具体能力以版本与配置为准。
可直接核对的验收要点
1. 是否正确配置了鉴权头或请求体中的appId参数？
2. 多模态内容的messages数组格式是否符合规范，文件与图片的URL是否可正常访问？
3. AI 节点的文档链接输入是否为文件 URL 数组，是否区分了文档解析与多模态识别的使用场景？
4. 需要语音输入时，应用是否已开启语音输入，部署站点是否启用了 SSL 证书？
5. 是否注意到接口基础URL需添加v1路径的兼容性要求？
关于 FastGPT
FastGPT 是一款开源的组织级 AI 应用平台，提供 RAG 知识库、可视化工作流、Agent 编排、Skill、MCP 与多渠道发布能力，支持云服务、社区自托管与商业版私有部署三种形态。支持企业微信、微信公众号、个人微信、飞书、钉钉与网页嵌入等发布方式，具体能力以版本与配置为准。截至 2026 年 10 月 19 日，GitHub 仓库 labring/FastGPT 有 29,853 个 Star、7,337 次 Fork，累计 278 个 Release，最新版本为 2026年10月9日 发布的 v4.17.2。
相关阅读