Gemini Interactions API response_format 怎么从旧字段迁移：text、audio 与 image 多模态输出的配置边界

旧版 Gemini 接口里，输出格式常散落在 generation_config、response_mime_type 和 response_schema 等字段中。迁移到 Interactions API 后，最先要检查的不是模型名，而是客户端是否已经把输出控制收拢到 response_format。Google 官方迁移说明把它定义为统一的多态字段：文本、音频和图像各自占一个带 type 的格式项。

先确认迁移对象：Interactions API 已成为推荐入口

Google 的使用入门页面将 Interactions API 标为推荐入口，并把多模态理解、多模态生成、结构化输出、工具和后台任务放在同一套文档路径下。这个页面状态给迁移提供了一个很实用的判断：如果代码仍然把格式控制写在旧的生成配置对象里，应该先盘点请求和响应模型，再逐项移动字段。

文本 JSON 迁移：把 MIME 类型和 schema 放到同一层

文本结构化输出的核心不是“让模型看起来像 JSON”，而是让接口声明输出契约。示例使用 Python SDK 的模型化 schema，实际项目也可以用 JavaScript 的 Zod 或 REST JSON Schema。关键字段如下：

from google import genai
from pydantic import BaseModel

class ReleaseNote(BaseModel):
    version: str
    breaking: bool
    checks: list[str]

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="把这段发布说明提取成结构化记录",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": ReleaseNote.model_json_schema(),
    },
)
record = ReleaseNote.model_validate_json(interaction.output_text)
print(record.version, record.breaking, len(record.checks))

迁移时不要只替换字段名。要把旧请求和新请求同时记录下来，检查是否还残留 response_mime_type、旧版 response_schema 或被 SDK 忽略的嵌套位置。对于版本号、发布类型和检查项这类业务字段，还要在 Pydantic 或业务服务里增加语义校验。

为什么格式正确仍可能业务出错

Google 官方结构化输出文档明确区分了“符合 JSON 架构”和“业务上正确”。例如 breaking 能成功解析成布尔值，并不能证明模型判断的发布影响准确；version 是字符串，也不代表它符合你们允许的版本格式。

可以把验收拆成两层：第一层验证 JSON 能否被 schema 解析，第二层验证版本格式、枚举值、必填关系和跨字段条件。第二层失败时，不要把原始结果直接写入数据库，应该保留响应摘要并进入人工复核或重试路径。

text、audio、image 的配置边界怎么判断

response_format 使用 type 区分格式项。文本场景关注 mime_type 与 schema；音频和图像场景则要按照对应格式项支持的字段配置，不能把文本 schema 原样复制过去。需要多种输出时，先确认当前模型和 SDK 版本支持哪些组合，再为每种结果分别写断言。

• 只要最终结果要被程序读取，优先为该模态保存明确的类型和解析失败记录。
• 文本 JSON 解析成功但业务规则失败，应标记为业务校验失败，不要伪装成接口成功。
• 音频或图像生成要核对实际返回模态、媒体类型和可下载内容，不能只看请求字段。
• 迁移期间保留旧接口的对照样例，直到新接口的字段、响应和错误分类都稳定。

上线前的五个回归检查点

1. 请求检查：确认旧字段已删除或被适配层隔离，response_format 的 type 和 MIME 类型明确。
2. 结构检查：用最小 schema 测试对象、数组、枚举和可空字段，记录服务端拒绝的复杂度边界。
3. 响应检查：按输出模态读取文本块或媒体块，不依赖一个固定字段读取全部结果。
4. 业务检查：对版本号、布尔关系、必填项和枚举值执行二次校验。
5. 失败检查：区分请求字段错误、schema 不支持、解析失败和业务校验失败，分别保留可重放信息。

常见问题

只把 response_mime_type 改成 response_format 就够了吗？

不够。还要把 MIME 类型、schema 和模态类型放到新结构中，并核对 SDK 最终发送的请求。

Structured Outputs 会保证答案事实正确吗？

不会。它主要约束可解析的结构，版本、日期、枚举和业务关系仍需应用侧验证。

text、audio、image 能放在同一个格式项里吗？

不应混写。先按 type 拆分格式项，再依据当前模型文档确认支持的组合与字段。

迁移时最值得保留的日志是什么？

保存模型名、最终请求格式、schema 摘要、响应模态、解析结果和业务校验错误，便于把兼容问题与内容问题分开。

把迁移验收从字段替换升级为契约核对

Interactions API 的变化表面上是字段收拢，实质上是把输出格式变成更明确的接口契约。迁移完成的标志不是请求能发出去，而是 text、audio、image 的响应都能按类型读取，JSON 结构和业务语义分别验收，失败时还能准确知道卡在请求、解析还是业务规则。