如何通过Gemini API上传多模态文件并调用推理接口？

Gemini API 针对图片、音频、视频、PDF 等非文本输入，提供了两种传递方式：一种是直接在请求体里放入 base64 编码的 inline_data，另一种是先通过 Files 服务上传到云端，再在推理时用 fileData 引用。对大文件或多轮复用的场景来说，后者明显更稳定，它能绕开 HTTP 请求体上限，也能减少每次请求的传输开销。本文聚焦文件上传与推理接口的配合方式，梳理从上传、状态确认到多模态提示词组织的完整链路，并给出可运行的 Python 与 curl 示例。

一、文件上传通道与前置限制

文件接口的核心资源是 files。Python SDK 将上传封装为 genai.upload_file，REST 客户端则向 /v1beta/files 发送 multipart 请求。上传成功后不要急着调用推理，因为文件可能还处于 PROCESSING 状态，需要轮询或短暂等待，直到状态变为 ACTIVE。免费账号通常有单文件 20MB 的限制，付费方案可以放宽到 2GB；文件在云端默认保留 48 小时，之后会被自动清理，因此生产环境需要设计重传或持久化元数据机制。

支持的文件类型覆盖主流多媒体格式：图片包括 PNG、JPEG、WEBP、HEIC、HEIF；视频常见 MP4、MOV、AVI、MPEG、WEBM；音频支持 WAV、MP3、AAC、FLAC；文档则主要是 PDF。纯文本文件也可以上传，但如果只是小段文本，放进提示词里通常更直接。上传时要显式提供 MIME 类型，错误类型会导致后续推理阶段无法正确解码。显示名称 display_name 是可选的，但建议填写，便于在文件列表里定位。

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

# 上传本地视频，display_name 便于在控制台或文件列表中识别
video_file = genai.upload_file(
    path="sample_video.mp4",
    display_name="会议录制示例"
)

print(f"已上传：{video_file.name}")
print(f"当前状态：{video_file.state.name}")

上面代码执行后，返回对象的 name 形如 files/abc123def456。这个 URI 是推理接口引用文件的关键凭证。大多数视频和音频文件在几秒内完成处理，但分辨率较高或时长较长的内容可能更久，建议用 get_file 查询状态，而不是盲目 sleep。状态枚举包括 STATE_UNSPECIFIED、PROCESSING、ACTIVE、FAILED，只有 ACTIVE 才表示模型可以读取。

二、在推理接口中引用 fileData

完成上传后，generateContent 请求不再直接携带二进制数据，而是用 file_data 指向云端 URI。Python SDK 支持更简洁的写法：直接把上传文件对象放进 contents 列表，SDK 内部会转换成对应的 fileData 结构。REST 调用则需要在 parts 数组里写清楚 mime_type 和 file_uri。这里的关键点是 file_uri 必须来自 files/ 前缀，不能用普通 HTTP 链接或云存储地址；模型只会从 Gemini 的文件服务中读取。

提示词组织上，多模态请求通常由文本 part 和文件 part 混合组成。模型会按照 parts 的顺序理解上下文，因此建议把指令性文本放在文件之前或之后保持一致，例如先用一行说明任务，再放文件引用。对于图片，可以直接要求模型描述对象、识别文字或判断差异；对于视频和音频，任务更适合总结、分段、提取关键时间点信息。单个请求里可以同时放多个文件，只要它们属于不同的 part，并且总 token 数不超过模型上下文窗口。

model = genai.GenerativeModel("gemini-1.5-pro")

response = model.generate_content([
    "请根据视频内容，提取会议中的行动项和负责人。",
    video_file
])

print(response.text)

如果使用 REST，可以发送如下 JSON。注意 file_uri 需要替换成实际上传后返回的 files/xxx。请求头保持 Content-Type: application/json，文件数据不要和 inline_data 同时使用，否则容易触发 400 错误。不同模型对 fileData 的支持范围略有差异，建议优先选择 gemini-1.5-pro 或支持多模态的系列，使用前查看模型能力说明。

curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro:generateContent?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "请总结这段音频的要点并列出时间戳"},
        {"file_data": {"mime_type": "audio/mp3", "file_uri": "files/abc123def456"}}
      ]
    }]
  }'

三、查询、删除与错误排查

文件上传后，本地不再需要维护文件内容，但需要维护 name 和 mime_type。为了及时清理无用文件，可以调用 delete_file 主动删除，虽然平台会在 48 小时后回收，但主动删除有助于避免配额占用和潜在的泄漏风险。文件列表接口 files.list 可以查看当前项目下所有文件及其状态，适合排查文件是否存在一类问题。

# 查询单个文件状态
file_info = genai.get_file(video_file.name)
print(file_info.state.name)  # ACTIVE / PROCESSING / FAILED

# 列出所有文件
for f in genai.list_files():
    print(f.name, f.state.name, f.display_name)

# 删除不再使用的文件
genai.delete_file(video_file.name)
print("文件已删除")

常见错误码中，404 表示 file_uri 无效或文件已经被清理，此时可以重新上传并更新 name。400 往往与 MIME 类型不匹配、parts 结构不合法、或文件仍处于 PROCESSING 状态有关。429 则是配额或速率限制，可以降低并发、增加重试间隔。FAILED 状态可能由于文件本身损坏、编码不支持或上传中断造成，应该检查源文件完整性并重新上传。

另一个容易被忽略的问题是超时。大视频或长音频的推理时间可能显著长于文本请求，Python SDK 默认超时时间不一定够用。可以在初始化客户端时调整请求超时参数，或采用异步任务思路，先提交请求再轮询结果。若业务允许，也可以提前用 ffmpeg 类工具抽帧或裁剪音频，减少模型需要处理的时长，从而降低失败概率和 token 消耗。

四、多文件组合与混合媒体推理

Gemini API 的 parts 设计支持在一个提示词里同时放入文本、图片、音频、视频和 PDF。例如你可以上传一份 PDF 说明书和一张产品图片，然后询问模型该图片是否符合文档中的规格。对于需要跨媒体比对的场景，不必把不同文件拼成一张图或转成统一格式，直接按 part 顺序传入即可。模型内部会分别编码不同模态，再在注意力层进行融合。

实际代码里，多文件上传可以使用循环处理，并为每个文件保存返回对象。推理时把所有文件对象或 fileData 一起放进 generateContent。需要注意各文件的总输入 token 会累加，大视频尤其明显，可能快速逼近上下文窗口。建议先用文件 API 确认每个文件大小和时长，估计 token 占用，必要时用分段策略：视频按时间切分，音频按章节切分，图片按需缩放后再上传。

pdf_file = genai.upload_file(path="manual.pdf", display_name="产品手册")
image_file = genai.upload_file(path="product.png", display_name="产品图")

response = model.generate_content([
    "参照产品手册，检查图片中的连接方式是否合规，并指出风险点。",
    pdf_file,
    image_file
])

print(response.text)

从工程角度看，每次运行都重新上传文件并不经济。更合理的方案是在文件首次上传后，把 name、mime_type、上传时间、哈希值写入业务数据库，后续请求直接复用。只要文件还在 48 小时有效期内，推理接口可以反复引用。定时任务可以根据上传时间判断哪些文件即将过期，必要时自动重传并更新数据库中的 name，这样上层推理逻辑无需感知文件生命周期。

最后要区分上传文件和给模型传文件两个动作。前者是向 Gemini 文件服务写入数据，后者是在 generateContent 中声明引用。两者拆开后，文件上传可以独立于推理进行，也可以在前端直传后把 file_uri 回传给后端。只要保证最终推理请求里的 file_uri 正确且文件处于 ACTIVE 状态，多模态推理就能跑通。对于需要私有化部署或数据合规要求较高的场景，则需要评估文件在云端保留 48 小时是否符合政策，必要时选择内联 base64 小文件方案作为补充。

Gemini API多模态文件推理接口修改时间：2026-09-23 17:06:30