Gemini API集成需掌握5大核心技术模块：一、模型标识与版本控制，须显式声明model字段并确认启用状态；二、内容结构化输入，强制使用content数组封装多模态数据；三、安全过滤器需逐条配置category与threshold；四、流式响应须处理SSE chunk并识别done标志；五、工具调用须严格遵循schema定义与三阶段闭环流程。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在集成 Gemini API 到应用中，但对官方文档结构不清晰、关键能力边界模糊，可能导致调用失败或功能误用。以下是 Gemini API 文档中开发者必须深入理解的 5 个核心技术模块：
一、模型标识与版本控制
Gemini API 通过 model 字段精确指定所调用的模型实例，不同 model 值对应不同的架构、上下文长度、训练截止时间及能力范围，错误指定将直接导致请求被拒绝或返回非预期响应。
1、在请求 JSON 的顶层字段中显式声明 model: "gemini-1.5-flash" 或 model: "gemini-1.5-pro"，不可省略或使用别名。
2、检查 Google AI Studio 或 Vertex AI 控制台中的可用模型列表，确认目标 model 当前处于 ENABLED 状态，部分模型需手动启用。
3、避免硬编码模型版本后缀（如 -001），优先使用无版本号的稳定别名，以兼容 Google 后续的透明升级策略。
二、内容结构化输入（Content Array）
Gemini API 不接受扁平字符串作为输入，强制要求将提示词、图像、音频等多模态数据封装为 content 数组，每个元素为 role + parts 组合，违反此结构将触发 400 错误。
1、构造 content 数组时，确保每个对象包含 role: "user" 或 role: "model" 字段，系统角色仅限于特定流式场景。
2、parts 字段必须为数组，单文本输入应写作 [{ "text": "你好" }]，而非字符串 "你好"。
3、插入 Base64 编码图像时，在 parts 中添加 { "inlineData": { "mimeType": "image/jpeg", "data": "base64-encoded-string" } }，mimeType 必须与实际二进制格式严格一致。
三、安全过滤器（Safety Settings）配置逻辑
安全过滤器并非全局开关，而是逐条作用于 content 数组中每个 part 的分类评估结果；未显式设置时采用默认阻断策略，可能导致合法内容被静默截断。
1、在请求体顶层添加 safetySettings 字段，其值为对象数组，每个对象含 category 和 threshold 两个必填键。
2、category 必须从预定义枚举中选择，例如 "HARM_CATEGORY_HARASSMENT"，拼写错误将被忽略且不报错。
3、threshold 可设为 "BLOCK_LOW_AND_ABOVE"、"BLOCK_MEDIUM_AND_ABOVE" 等四级值，不可使用自定义字符串或数字。
四、流式响应（Streaming）状态机管理
启用 stream: true 后，API 返回多个 SSE 格式 chunk，每个 chunk 并非完整响应片段，而是增量 token 流；客户端必须按顺序拼接并识别 done 标志，否则将解析出错或丢失末尾内容。
1、HTTP 请求头中必须包含 Accept: "text/event-stream"，缺失将导致 406 Not Acceptable 错误。
2、逐行读取响应 body，每行以 data: 开头，提取其后 JSON 字符串并解析，忽略空行和注释行（以 : 开头的行）。
3、检测到包含 "done": true 的 chunk 时立即终止接收，该 chunk 的 candidates 字段可能为空，最终结果需合并此前所有 candidates 的 content 字段。
五、工具调用（Function Calling）协议规范
工具调用不是自由函数执行，而是严格遵循 schema 定义 + 模型生成 + 客户端验证的三阶段闭环；任意环节 schema 不匹配，将导致工具参数解析失败或调用跳过。
1、在请求中传入 tools 字段，其值为对象数组，每个对象的 function 字段内必须包含 name、description、parameters 三个键，parameters 需符合 JSON Schema Draft 7 子集。
2、模型返回的 function_call 字段中，name 值必须与 tools 中某 function.name 完全一致（大小写敏感），否则视为无效调用。
3、调用函数后，将结果以 {"name": "xxx", "content": "{...}"} 格式构造新 content 元素，作为下一轮请求的 user 角色输入，不可嵌套或修改结构。
