Gemini の Interactions API(v1beta)で、レスポンスの形が静かに、しかし根こそぎ変わった。outputs 配列が steps 配列に置き換わる破壊的変更だ。5月20日には新スキーマがデフォルトになり、6月6日には旧スキーマが消える。つまり「まだ動いているコード」が、来月には黙って壊れる側にいるかもしれない。私が気づいたのは、レスポンスの取り出し位置が一段深くなっていたからだった。
結論から:6/6までに steps 対応が要る
先に答えを置く。Interactions API を使っているなら、6月6日までに steps ベースのパースへ書き換えるのが必須だ。猶予はあるが、期限は固定されている。
ポイントは三つ。まずレスポンスの本体が outputs から steps に変わった。次に response_mime_type が廃止され、response_format に統合された。そしてストリーミングのイベント名も総入れ替えになっている。
逆に言えば、リクエストの送り方(model や input、ツール指定)はほぼそのまま。壊れるのは「受け取り側」だけだ。ここを直せば移行は終わる。
outputs が steps に変わる、という話
旧スキーマは、モデルの生成内容だけを平らな outputs 配列で返していた。新スキーマの steps は、一つの応答ターンを「ステップの時系列」として返す。各ステップには type 判別子が付く。user_input、thought、function_call、model_output といった具合だ。
テキストの取り出しはこう変わる。
# 旧(legacy)
print(interaction.outputs[0].text)
# 新(steps)
print(interaction.steps[-1].content[0].text)地味だが効く違いがある。POST /interactions は出力ステップだけを返すのに対し、GET /interactions/{id} は user_input を含むフル時系列を返す。会話履歴を自前管理している人(ステートレス運用)は、次のターンで outputs を詰め直していたところを、steps 配列ごと input に渡す形へ直す必要がある。ここを見落とすと履歴が片肺になる。
response_mime_type は消えた、response_format に寄せる
もう一つの破壊的変更がこれ。出力フォーマットの指定が response_format に一本化された。response_mime_type というトップレベルのフィールドはもう無い。
# 旧
client.interactions.create(
model="gemini-3-flash-preview",
input="記事を要約して",
response_mime_type="application/json",
response_format={"type": "object", "properties": {"summary": {"type": "string"}}},
)
# 新:mime_type と schema を response_format の中に入れる
client.interactions.create(
model="gemini-3-flash-preview",
input="記事を要約して",
response_format={
"type": "text",
"mime_type": "application/json",
"schema": {"type": "object", "properties": {"summary": {"type": "string"}}},
},
)画像生成の image_config も generation_config から response_format("type": "image")へ引っ越した。generation_config は temperature や thinking といった「モデルの振る舞い」専用に痩せた、という整理だ。個人的にはこの線引きは好み。設定の置き場が散らからない。
公式サンプルを手元でパースして差分を測った
翻訳記事で終わらせたくないので、公式の before/after サンプル(Google Search を使う応答)を手元のスクリプトに食わせて、何行直せば済むのかを実際に確かめた。
# 新スキーマで最終テキストを取る
def get_text_new(r):
for s in r["steps"]:
if s["type"] == "model_output":
for c in s["content"]:
if c["type"] == "text":
return c["text"]実測で見えた落とし穴は二つ。
一つ、引用(annotation)のキーが変わっていた。旧は start_index・end_index・source の3キー。新は source が url に変わり、さらに type(url_citation)と title が増えて5キーになる。引用元URLを source で読んでいるコードは、ここで None を掴む。
二つ、サーバー側ツールの結果キーも別物だった。Google Search の結果は旧 rendered_content から新 search_suggestions へ。HTMLを取り出して描画していた箇所は、まず確実に壊れる。これは公式の「移行チェックリスト」には太字で書かれていない。地雷は端にある、という典型だ。
ストリーミングと移行スケジュール
ストリーミングはイベント名がまるごと変わった。content.start → step.start、content.delta → step.delta、content.stop → step.stop。完了通知の interaction.complete は interaction.status_update(status: "completed")に吸収された。ストリーム関数呼び出しでは、step.start が関数名を、step.delta が引数を部分JSON(arguments_delta)で流す。差分を自分で連結して組み立てる必要がある。
移行の段取りはこうだ。
# REST はヘッダで新スキーマにオプトイン
Api-Revision: 2026-05-20
# 5/20以降に一時的に旧へ戻したいとき(6/6まで)
Api-Revision: 2026-05-06SDK 利用者は 2.x 系へ上げれば自動で新スキーマになる。受け取り方を直す以外のコード変更は要らない。1.x 系は当面動くが、6月6日に Interactions API 呼び出しが動かなくなる。これは Vim 時代の「プラグインのAPIが一斉に変わって、放置していた設定が一日で壊れた」あの感覚に近い。動いているうちに直すのが結局いちばん安い。
限界・注意点と私見
注意点を正直に。今回のスキーマ変更は v1beta の Interactions API に閉じた話で、従来の generateContent を叩いている人には直接関係しない。自分がどちらのエンドポイントを使っているかをまず確認したい。
それと公式は「5月7日以降に出る新機能は steps 応答にしか乗らない」と明記している。旧スキーマに居座る限り、新機能は一切降ってこない。互換性のために残っているのではなく、置いていかれる側として残っている、という温度感だ。
私見を言えば、steps 化はミッドフライト操舵や非同期ツール呼び出しを見据えた布石で、方向としては正しい。ただ「デフォルト切替(5/20)」と「廃止(6/6)」の間が2週間ちょっとと短い。プレビューの宿命とはいえ、本番投入していたチームには厳しい。次に試すのは、steps を時系列ログとしてそのまま保存し、thought ステップを観測に回す運用だ。フラットな outputs ではできなかった、応答の途中経過を構造のまま残せる。そこに今回の変更の実利がある気がしている。
