Interactions API: Migrationsanleitung für Breaking Changes (Mai 2026)

Mit der v1beta Interactions API werden grundlegende Änderungen eingeführt, die die API-Struktur neu organisieren, um zukünftige Funktionen wie die Steuerung während der Ausführung und asynchrone Tool-Aufrufe zu unterstützen. Auf dieser Seite wird erläutert, was sich ändert, und es werden Codebeispiele vor und nach der Änderung bereitgestellt, um Ihnen die Migration zu erleichtern. Es gibt zwei Kategorien von Änderungen:

  1. Schritte-Schema: Ein neues steps Array ersetzt das outputs Array und bietet eine strukturierte Zeitachse für jede Interaktion.
  2. Konfiguration des Ausgabeformats: Ein neues polymorphes response_format fasst alle Steuerelemente für das Ausgabeformat zusammen und entfernt response_mime_type.

Folgen Sie der Anleitung unter Zu neuem Schema migrieren, um Ihre Integration zu aktualisieren.

Wichtige Änderung: outputs zu steps

Das neue Schema ersetzt das outputs-Array durch ein steps-Array.

  • Altes Schema: Antworten haben ein flaches outputs Array zurückgegeben, das nur die vom Modell generierten Inhalte enthielt.
  • Neues Schema: Antworten geben ein steps-Array zurück, das sowohl die wiederholten Nutzereingaben als auch die Modellausgaben enthält und so eine vollständige Zeitachse der Interaktion bietet.

Unäre (nicht streamende) Antworten wiederholen Ihre Eingabe als ersten Schritt im steps-Array. Bei Streaming-Antworten wird der Eingabeschritt übersprungen und es werden nur Deltas für generierte Inhalte ausgegeben.

Einfache Eingabe/Ausgabe (unär)

Vorher (altes Schema)

Python

# Request
interaction = client.interactions.create(
    model="gemini-3-flash-preview", input="Tell me a joke."
)

# Response access
print(interaction.outputs[0].text)

JavaScript

// Request
const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Tell me a joke.'
});

// Response access
console.log(interaction.outputs[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Tell me a joke."
}

// Response
{
  "id": "int_123",
  "role": "model",
  "outputs": [
    {
      "type": "text",
      "text": "Why did the chicken cross the road?"
    }
  ]
}

Nachher (neues Schema)

Python

# Request
interaction = client.interactions.create(
    model="gemini-3-flash-preview", input="Tell me a joke."
)

# Response access
print(interaction.steps[-1].content[0].text)  # CHANGED: steps instead of outputs

JavaScript

// Request
const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Tell me a joke.'
});

// Response access
console.log(interaction.steps.at(-1).content[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Tell me a joke."
}

// Response
{
  "id": "int_123",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Tell me a joke."
        }
      ]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

Funktionsaufrufe

Die Anfragestruktur bleibt unverändert, aber die Antwort ersetzt den flachen outputs-Inhalt durch strukturierte Schritte.

Vorher (altes Schema)

Python

# Accessing function call in legacy schema
for output in interaction.outputs:
    if output.type == "function_call":
        print(f"Calling {output.name} with {output.arguments}")

JavaScript

// Accessing function call in legacy schema
for (const output of interaction.outputs) {
    if (output.type === 'function_call') {
        console.log(`Calling {output.name} with {JSON.stringify(output.arguments)}`);
    }
}

REST

// Response
{
  "id": "int_001",
  "role": "model",
  "status": "requires_action",
  "outputs": [
    {
      "type": "thought",
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]
}

Nachher (neues Schema)

Python

# Accessing function call in new steps schema
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Calling {step.name} with {step.arguments}")

JavaScript

// Accessing function call in new steps schema
for (const step of interaction.steps) {
    if (step.type === 'function_call') {
        console.log(`Calling {step.name} with {JSON.stringify(step.arguments)}`);
    }
}

REST

// Response
{
  "id": "int_001",
  "status": "requires_action",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        { "type": "text", "text": "What's the weather in Boston?" }
      ]
    },
    {
      "type": "thought",
      "status": "done",
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "status": "waiting",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]
}

Serverseitige Tools

Serverseitige Tools wie die Google Suche oder die Codeausführung liefern jetzt bestimmte Schritttypen im steps-Array. Während das alte Schema diese Vorgänge als bestimmte Inhaltstypen im outputs-Array zurückgegeben hat, verschiebt das neue Schema sie in das steps-Array. In den folgenden Beispielen wird die Google Suche verwendet.

Vorher (altes Schema)

Python

# Accessing search results in legacy schema
for output in interaction.outputs:
    if output.type == "google_search_call":
        print(f"Searched for: {output.arguments.queries}")
    elif output.type == "google_search_result":
        print(f"Found results: {output.result.rendered_content}")

JavaScript

// Accessing search results in legacy schema
for (const output of interaction.outputs) {
    if (output.type === 'google_search_call') {
        console.log(`Searched for: {output.arguments.queries}`);
    } else if (output.type === 'google_search_result') {
        console.log(`Found results: {output.result.renderedContent}`);
    }
}

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Who won the last Super Bowl?",
  "tools": [
    { "type": "google_search" }
  ]
}

// Response
{
  "id": "int_456",
  "outputs": [
    {
      "type": "google_search_call",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] }
    },
    {
      "type": "google_search_result",
      "call_id": "gs_1",
      "result": {
        "rendered_content": "<div>...</div>",
        "url": "https://www.nfl.com/super-bowl"
      }
    },
    {
      "type": "text",
      "text": "The Kansas City Chiefs won the last Super Bowl.",
      "annotations": [
        {
          "start_index": 4,
          "end_index": 22,
          "source": "https://www.nfl.com/super-bowl"
        }
      ]
    }
  ],
  "status": "completed"
}

Nachher (neues Schema)

Python

# Accessing search results in new steps schema
for step in interaction.steps:
    if step.type == "google_search_call":
        print(f"Searched for: {step.arguments.queries}")
    elif step.type == "google_search_result":
        print(f"Found results: {step.result.search_suggestions}")

JavaScript

// Accessing search results in new steps schema
for (const step of interaction.steps) {
    if (step.type === 'google_search_call') {
        console.log(`Searched for: {step.arguments.queries}`);
    } else if (step.type === 'google_search_result') {
        console.log(`Found results: {step.result.searchSuggestions}`);
    }
}

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Who won the last Super Bowl?",
  "tools": [
    { "type": "google_search" }
  ]
}

// Response
{
  "id": "int_456",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        { "type": "text", "text": "Who won the last Super Bowl?" }
      ]
    },
    {
      "type": "google_search_call",
      "status": "done",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] },
      "signature": "abc123..."
    },
    {
      "type": "google_search_result",
      "status": "done",
      "call_id": "gs_1",
      "result": {
        "search_suggestions": "<div>...</div>"
      },
      "signature": "abc123..."
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "The Kansas City Chiefs won the last Super Bowl.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.nfl.com/super-bowl",
              "title": "NFL.com",
              "start_index": 4,
              "end_index": 22
            }
          ]
        }
      ]
    }
  ],
  "status": "completed"
}

Streaming

Streaming bietet neue Ereignistypen:

Neue Ereignistypen

  • interaction.created
  • interaction.status_update – umfasst jetzt alle Lebenszyklusphasen, einschließlich Abschluss und Fehler (siehe Status unten)
  • step.start
  • step.delta
  • step.stop
Status für interaction.status_update
  • in_progress
  • active
  • completed
  • interrupted
  • requires_action
  • error

Eingestellte Ereignistypen

Die folgenden alten Ereignistypen werden durch die oben aufgeführten neuen Ereignisse ersetzt:

  • interaction.start → interaction.created
  • content.start → step.start
  • content.delta → step.delta
  • content.stop → step.stop
  • interaction.complete → interaction.status_update mit status: "completed"
  • error → interaction.status_update mit status: "error"
  • interaction.status_update → interaction.status_update (unverändert, umfasst aber jetzt zusätzliche Status)

Streaming-Funktionsaufrufe: Wenn Sie Streaming mit Funktionsaufrufen verwenden, liefert das step.start-Ereignis den Funktionsnamen und step.delta-Ereignisse streamen die Argumente als teilweise JSON-Strings (mit arguments_delta). Sie müssen diese Deltas zusammenführen, um die vollständigen Argumente zu erhalten. Dies unterscheidet sich von unären Aufrufen, bei denen Sie das vollständige Funktionsaufrufobjekt auf einmal erhalten.

Beispiele

Vorher (altes Schema)

Python

# Legacy streaming used content.delta
stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain quantum entanglement in simple terms.",
    stream=True,
)

for chunk in stream:
    if chunk.event_type == "content.delta":
        if chunk.delta.type == "text":
            print(chunk.delta.text, end="", flush=True)

JavaScript

// Legacy streaming used content.delta
const stream = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Explain quantum entanglement in simple terms.',
    stream: true,
});

for await (const chunk of stream) {
    if (chunk.event_type === 'content.delta') {
        if (chunk.delta.type === 'text') {
            process.stdout.write(chunk.delta.text);
        }
    }
}

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Explain quantum entanglement in simple terms.",
  "stream": true
}

// Response (SSE Lines)
// event: interaction.start
// data: {"id": "int_123", "status": "in_progress"}
//
// event: content.start
// data: {"index": 0, "type": "text"}
//
// event: content.delta
// data: {"delta": {"type": "text", "text": "Quantum entanglement is..."}}
//
// event: content.stop
// data: {"index": 0}
//
// event: interaction.complete
// data: {"id": "int_123", "status": "done", "usage": {"total_tokens": 42}}
Nachher (neues Schema)

Python

# Consuming stream and handling new event types
for event in client.interactions.create(
    model="gemini-3-flash-preview",
    input="Tell me a story.",
    stream=True,
):
    if event.type == "step.delta":  # CHANGED: step.delta instead of content.delta
        if event.delta.type == "text":
            print(event.delta.text, end="")

JavaScript

// Consuming stream and handling new event types
const stream = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Tell me a story.',
    stream: true,
});

for await (const event of stream) {
    if (event.type === 'step.delta') {  // CHANGED: step.delta instead of content.delta
        if (event.delta.type === 'text') {
            process.stdout.write(event.delta.text);
        }
    }
}

REST

 // Request: POST /v1beta/interactions
 // Accept: text/event-stream
 {
   "model": "gemini-3-flash-preview",
   "input": "Tell me a story."
 }

 // Response (SSE Lines)
 // event: interaction.created
 // data: {"type": "interaction.created", "interaction": {"id": "int_xyz", "status": "created"}} // CHANGED: 'type' instead of 'event_type'
 //
 // event: interaction.status_update
 // data: {"type": "interaction.status_update", "status": "in_progress"} // NEW: Lifecycle status updates in stream (postpone until Sessions launch dependency)
 //
 // event: step.start
 // data: {"type": "step.start", "index": 0, "step": {"type": "thought"}} // NEW: Replaces content.start, 'step' instead of 'content'
 //
 // event: step.delta
 // data: {"type": "step.delta", "index": 0, "delta": {"type": "thought", "text": "User wants an explanation."}} // NEW: Delta type matches step type
 //
 // event: step.stop
 // data: {"type": "step.stop", "index": 0, "status": "done"} // NEW: Includes status
 //
 // event: step.start
 // data: {"type": "step.start", "index": 1, "step": {"type": "model_output"}} // NEW: Step wrapper for output
 //
 // event: step.delta
 // data: {"type": "step.delta", "index": 1, "delta": {"type": "text", "text": "Hello"}}
 //
 // event: step.stop
 // data: {"type": "step.stop", "index": 1, "status": "done"}
 //
 // event: interaction.complete
 // data: {"type": "interaction.complete", "interaction": {"id": "int_xyz", "status": "completed", "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}}} // NEW: End of stream event with interaction details

Zustandsloser Unterhaltungsverlauf

Wenn Sie den Unterhaltungsverlauf manuell auf der Clientseite verwalten (zustandsloser Anwendungsfall), müssen Sie die Art und Weise aktualisieren, wie Sie vorherige Interaktionen verknüpfen.

  • Altes Schema: Entwickler haben oft das outputs-Array aus Antworten erfasst und in der nächsten Interaktion im Feld input zurückgesendet.
  • Neues Schema: Sie sollten jetzt das steps-Array aus der Antwort erfassen und im Feld input der nächsten Anfrage übergeben. Fügen Sie Ihre neue Nutzerinteraktion als user_input-Schritt hinzu.

Konfiguration des Ausgabeformats: Änderungen an response_format

Die aktualisierte API fasst alle Steuerelemente für das Ausgabeformat in einem einheitlichen, polymorphen response_format-Feld zusammen. Dadurch wird die Ausgabekonfiguration auf oberster Ebene zentralisiert und generation_config konzentriert sich auf das Modellverhalten (z. B. Temperatur, top_p und Denkprozess).

Wichtigste Änderungen

  • Die API entfernt response_mime_type. Sie geben den MIME-Typ jetzt pro Formateintrag in response_format an.
  • response_format ist jetzt ein polymorphes Objekt (oder Array). Jeder Eintrag hat einen type-Diskriminator (text, audio, image) und typspezifische Felder. Wenn Sie mehrere Ausgabemodalitäten anfordern möchten, übergeben Sie ein Array von Formateinträgen.
  • image_config wird von generation_config zu response_format verschoben. Sie geben jetzt Einstellungen für die Bildausgabe wie aspect_ratio und image_size in einem response_format Eintrag mit "type": "image" an.

Strukturierte Ausgabe (JSON)

Das neue Schema entfernt das Feld response_mime_type. Geben Sie stattdessen den MIME-Typ und das JSON-Schema in einem response_format Objekt mit "type": "text" an.

Vorher (altes Schema)

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Summarize this article.",
    response_mime_type="application/json",
    response_format={
        "type": "object",
        "properties": {
            "summary": {"type": "string"}
        }
    },
)

print(interaction.outputs[0].text)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Summarize this article.',
    responseMimeType: 'application/json',
    responseFormat: {
        type: 'object',
        properties: {
            summary: { type: 'string' }
        }
    },
});

console.log(interaction.outputs[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Summarize this article.",
  "response_mime_type": "application/json",
  "response_format": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" }
    }
  }
}

Nachher (neues Schema)

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Summarize this article.",
    # response_mime_type is removed — specify mime_type inside response_format
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "type": "object",
            "properties": {
                "summary": {"type": "string"}
            }
        }
    },
)

print(interaction.steps[-1].content[0].text)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Summarize this article.',
    // responseMimeType is removed — specify mimeType inside responseFormat
    responseFormat: {
        type: 'text',
        mimeType: 'application/json',
        schema: {
            type: 'object',
            properties: {
                summary: { type: 'string' }
            }
        }
    },
});

console.log(interaction.steps.at(-1).content[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Summarize this article.",
  // response_mime_type is removed
  "response_format": {
    "type": "text",                          // NEW: type discriminator
    "mime_type": "application/json",          // MOVED: from response_mime_type
    "schema": {                              // RENAMED: was response_format directly
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      }
    }
  }
}

Image-Konfiguration

Das neue Schema entfernt image_config aus generation_config. Sie geben jetzt Einstellungen für die Bildausgabe in einem response_format Eintrag mit "type": "image" an.

Vorher (altes Schema)

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Generate an image of a sunset over the ocean.",
    generation_config={
        "image_config": {
            "aspect_ratio": "1:1",
            "image_size": "1K"
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Generate an image of a sunset over the ocean.',
    generationConfig: {
        imageConfig: {
            aspectRatio: '1:1',
            imageSize: '1K'
        }
    },
});

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Generate an image of a sunset over the ocean.",
  "generation_config": {
    "image_config": {
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }
}

Nachher (neues Schema)

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Generate an image of a sunset over the ocean.",
    # image_config is removed from generation_config — use response_format
    response_format={
        "type": "image",
        "mime_type": "image/jpeg",
        "delivery": "inline",
        "aspect_ratio": "1:1",
        "image_size": "1K"
    },
)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Generate an image of a sunset over the ocean.',
    // imageConfig is removed from generationConfig — use responseFormat
    responseFormat: {
        type: 'image',
        mimeType: 'image/jpeg',
        delivery: 'inline',
        aspectRatio: '1:1',
        imageSize: '1K'
    },
});

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Generate an image of a sunset over the ocean.",
  // image_config removed from generation_config
  "response_format": {
    "type": "image",                         // NEW: type discriminator
    "mime_type": "image/jpeg",
    "delivery": "inline",
    "aspect_ratio": "1:1",                   // MOVED: from generation_config.image_config
    "image_size": "1K"                       // MOVED: from generation_config.image_config
  }
}

Wenn Sie mehrere Ausgabemodalitäten anfordern möchten (z. B. Text und Audio zusammen), übergeben Sie ein Array von Formateinträgen an response_format anstelle eines einzelnen Objekts.

Zu neuem Schema migrieren

SDK-Nutzer

Führen Sie ein Upgrade auf die neueste SDK-Version durch (Python ≥1.76.0, JavaScript ≥1.53.0). Das SDK aktiviert automatisch das neue Schema. Es sind keine Codeänderungen erforderlich, außer wie Sie Antworten lesen (siehe Beispiele oben). Beachten Sie, dass in diesen SDK-Versionen nur das neue Schema unterstützt wird. Ältere SDK-Versionen (Python ≤1.73.1, JavaScript ≤1.50.1) funktionieren weiterhin, bis das alte Schema am 6. Juni 2026 entfernt wird.

REST API-Nutzer

Fügen Sie Ihren Anfragen den Header Api-Revision: 2026-05-20 hinzu, um jetzt das neue Schema zu aktivieren. Nach dem 20. Mai wird das neue Schema für alle Anfragen zur Standardeinstellung. Sie können es vorübergehend mit Api-Revision: 2026-05-06 deaktivieren, bis das alte Schema am 6. Juni dauerhaft aus der API entfernt wird.

Zeitachse

Datum Phase SDK-Nutzer REST API-Nutzer
6. Mai Opt-in Neue Hauptversion des SDK verfügbar (Python ≥2.0.0, JS ≥2.0.0). Führen Sie ein Upgrade durch, um das neue Schema automatisch zu erhalten. Fügen Sie den Header Api-Revision: 2026-05-20 hinzu, um das neue Schema zu aktivieren. Das alte Schema bleibt die Standardeinstellung.
20. Mai Standardeinstellung geändert Wenn Sie bereits ein Upgrade durchgeführt haben, sind keine Maßnahmen erforderlich. Ältere SDKs (Python 1.x.x, JS 1.x.x) funktionieren weiterhin, geben aber Antworten im alten Schema zurück. Das neue Schema ist jetzt die Standardeinstellung. Senden Sie den Header Api-Revision: 2026-05-06, um das neue Schema zu deaktivieren.
6. Juni Sonnenuntergang Die SDK-Versionen 1.x.x für Python und JS funktionieren nicht mehr für Aufrufe der Interactions API. Das alte Schema wurde für die Interactions API entfernt. Der Header Api-Revision wird ignoriert.

Checkliste für die Migration

Schritte-Schema (steps)

  • Aktualisieren Sie den Code, um Antwortinhalte aus dem steps-Array anstelle von outputs zu lesen. Beispiele ansehen
  • Prüfen Sie, ob Ihr Code sowohl die Schritttypen user_input als auch model_output verarbeitet. Beispiele ansehen
  • (Funktionsaufrufe) Aktualisieren Sie den Code, um function_call-Schritte im steps-Array zu finden. Beispiele ansehen
  • (Serverseitige Tools) Aktualisieren Sie den Code, um toolspezifische Schritte zu verarbeiten (z.B. google_search_call, google_search_result). Beispiele ansehen.
  • (Zustandsloser Verlauf) Aktualisieren Sie die Verlaufsverwaltung, um das steps-Array im Feld input der nächsten Anfrage zu übergeben. Details ansehen.
  • (Nur Streaming) Aktualisieren Sie den Client, um auf neue SSE-Ereignistypen zu warten (interaction.created, step.delta usw.). Beispiele ansehen.

Konfiguration des Ausgabeformats (response_format)

  • Ersetzen Sie response_mime_type durch ein mime_type-Feld in response_format. Beispiele ansehen.
  • Umschließen Sie Ihr vorhandenes response_format JSON-Schema mit einem {"type": "text", "schema": ...} Objekt. Beispiele ansehen.
  • (Bildgenerierung) Verschieben Sie image_config von generation_config zu einem {"type": "image", ...}-Eintrag in response_format. Beispiele ansehen.
  • (Multimodal) Konvertieren Sie response_format von einem einzelnen Objekt in ein Array, wenn Sie mehrere Ausgabemodalitäten anfordern.