Google Gemini API多模态输入怎么用？Safety Settings安全设置配置详解

Gemini API是Google推出的大模型服务接口，和传统只能处理文本的API不同，它原生支持文本、图片、音频、视频等多种输入混合提交。很多人第一次调用时会在两个地方卡住：一是多模态数据到底怎么传，传base64还是走File API；二是明明内容很正常，返回结果却提示被SAFETY策略拦截，不知道去哪里调整。这篇文章就把这两个问题一次讲清楚，并附上可以直接跑通的代码。

多模态输入的两种方式：inline直传与File API上传

Gemini API接收非文本数据时，本质上是把二进制内容编码后放进请求体的parts数组里。官方提供了两种途径。第一种是inline方式，把文件读出来做base64编码，直接嵌入请求。这种方式最简单，适合小文件，官方建议单个请求内inline内容总量控制在20MB以内。图片识别、小段音频转写这类场景用它就够了。

第二种是File API上传。当文件超过20MB，或者你希望在多个请求中复用同一个文件（比如先总结视频再针对视频提问），就应该先把文件上传到Google的服务器，拿到一个file URI，之后每次请求只传这个URI。上传后的文件会保留48小时，期间可以反复引用，避免了每次都传几百MB的重复开销，对视频类任务尤其友好。

下面是一段同时演示两种方式的Python代码，注意File API的调用顺序是先上传再轮询状态，文件变成ACTIVE后才能发起generate_content请求：

import base64
import time
import google.generativeai as genai

genai.configure(api_key="你的API Key")
model = genai.GenerativeModel("gemini-1.5-flash")

# 方式一：inline直传，适合小图片
with open("test.jpg", "rb") as f:
    img_data = base64.b64encode(f.read()).decode()

resp = model.generate_content(
    [
        {"text": "描述这张图片的内容"},
        {"inline_data": {"mime_type": "image/jpeg", "data": img_data}}
    ]
)
print(resp.text)

# 方式二：File API上传，适合大视频
video_file = genai.upload_file(path="demo.mp4", display_name="演示视频")
while video_file.state.name == "PROCESSING":
    time.sleep(5)
    video_file = genai.get_file(video_file.name)

resp2 = model.generate_content(
    ["请总结这段视频讲了什么", video_file]
)
print(resp2.text)

除了手动上传本地文件，还可以直接传公开的YouTube视频链接或视频URL，模型会自行拉取内容，这在网上公开课总结、会议录像提取要点等场景非常省事。另外JSON、CSV这类结构化文本也算多模态输入的一部分，通过inline_data传给模型后可以让它做数据分析，不需要额外转换格式。

Safety Settings配置：四类维度与阈值详解

Gemini API默认自带一套安全过滤策略，覆盖四个维度：HARASSMENT（骚扰）、HATE_SPEECH（仇恨言论）、SEXUALLY_EXPLICIT（色情内容）、DANGEROUS_CONTENT（危险内容）。每个维度都可以单独设置过滤阈值，从松到严共有五档：BLOCK_NONE、BLOCK_ONLY_HIGH、BLOCK_MEDIUM_AND_ABOVE、BLOCK_LOW_AND_ABOVE、HARM_BLOCK_THRESHOLD_UNSPECIFIED。默认值通常是BLOCK_MEDIUM_AND_ABOVE，也就是中等及以上风险就拦截，这就是为什么有些正常请求也会被误伤的原因。

配置方法是在generate_content时传入safety_settings参数，它是一个字典列表，每个元素指定category和threshold。Python SDK的写法如下：

from google.generativeai.types import HarmCategory, HarmBlockThreshold

safety_settings = [
    {
        "category": HarmCategory.HARM_CATEGORY_HARASSMENT,
        "threshold": HarmBlockThreshold.BLOCK_ONLY_HIGH
    },
    {
        "category": HarmCategory.HARM_CATEGORY_HATE_SPEECH,
        "threshold": HarmBlockThreshold.BLOCK_ONLY_HIGH
    },
    {
        "category": HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
        "threshold": HarmBlockThreshold.BLOCK_ONLY_HIGH
    },
    {
        "category": HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
        "threshold": HarmBlockThreshold.BLOCK_ONLY_HIGH
    },
]

response = model.generate_content(
    contents="讲一个关于程序员加班的黑色幽默",
    safety_settings=safety_settings
)
print(response.text)

设置成BLOCK_NONE可以完全关闭某个维度的过滤，但在多数模型版本上这个选项仅对部分受信任账号开放，普通账号传了会报400错误。比较稳妥的做法是用BLOCK_ONLY_HIGH，只拦截高风险内容，日常应用的误判率会明显下降。另外需要注意，即使prompt没有被拦截，个别candidate也可能因为输出触发了安全策略而返回finish_reason为SAFETY的空结果，这时可以检查response.candidates[0].safety_ratings字段，它会把每个维度的实际评级列出来，方便定位到底是哪一项触发了拦截。

还有一点容易踩坑：安全设置对多模态输入同样生效。一张图片即使prompt无害，如果图片内容本身被判定为涉及敏感维度，同样会被拦截。所以做图片审核、医疗影像分析这类应用时，合理调低对应维度的阈值几乎是必须的操作，否则业务流程会频繁中断。

常见报错与最佳实践

多模态调用常见的报错有几种。429错误表示触发限流，免费档对每分钟请求数和每分钟token数都有上限，视频这类大输入特别容易把token额度打满，建议加指数退避重试。400错误里如果提示API key not valid，先确认key来源的区域，某些地区的key不能调用特定模型。上传文件时如果报Failed to fetch，多半是文件超过2GB的上限或者mime type不支持，支持的图片格式包括PNG、JPEG、WebP，音频支持WAV、MP3、AIFF、AAC、OGG，视频支持MP4、MPEG、MOV、AVI、FLV。

在架构设计上，建议把安全设置抽成可配置项而不是写死在代码里。比如做一个后台管理界面，让运营人员根据业务形态调整各维度阈值：儿童教育类应用保持默认的严格档位，新闻聚合类应用放宽到BLOCK_ONLY_HIGH。同时记录每次请求的safety_ratings到日志，定期统计拦截率，如果某个维度误判比例异常高，再针对性调整，这比一开始就全关过滤要合理得多。

最后提醒一点，随意把所有安全维度设置成BLOCK_NONE虽然能让调用畅通无阻，但意味着你的应用失去了平台侧的内容兜底，一旦用户输入恶意内容并产生有害输出，责任会完全落在应用方。Google的官方文档也明确说明，安全过滤的调整应当在符合当地法规和平台政策的前提下进行。配合系统指令（system_instruction）约束模型的行为边界，再辅以合理的阈值配置，才是长期稳定的方案。

Gemini API多模态输入Safety Settings修改时间：2026-09-11 05:36:30