API Interactions: guida alla migrazione delle modifiche che causano interruzioni (maggio 2026)

L'API Interactions v1beta introduce modifiche che causano interruzioni e che ristrutturano la forma dell'API per supportare funzionalità future come l'orientamento in corso e le chiamate di strumenti asincrone. Questa pagina spiega cosa sta cambiando e fornisce esempi di codice prima e dopo per aiutarti a eseguire la migrazione. Esistono due categorie di modifiche:

  1. Schema dei passaggi: un nuovo array steps sostituisce l'array outputs, fornendo una sequenza temporale strutturata di ogni turno di interazione.
  2. Configurazione del formato di output: un nuovo response_format polimorfico consolida tutti i controlli del formato di output e rimuove response_mime_type.

Segui i passaggi descritti in Come eseguire la migrazione al nuovo schema per aggiornare l'integrazione.

Modifica principale: da outputs a steps

Il nuovo schema sostituisce l'array outputs con un array steps.

  • Precedente: le risposte restituivano un array outputs flat contenente solo i contenuti generati dal modello.
  • Nuovo schema: le risposte restituiscono un array steps che include sia gli input utente ripetuti sia gli output del modello, fornendo una sequenza temporale completa del turno di interazione.

Le risposte unarie (non in streaming) ripetono l'input come primo passaggio nell'array steps. Le risposte in streaming saltano il passaggio di input ed emettono solo delta di contenuti generati.

Input/output di base (unario)

Prima (precedente)

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?"
    }
  ]
}

Dopo (nuovo 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?"
        }
      ]
    }
  ]
}

Chiamata di funzione

La struttura della richiesta rimane invariata, ma la risposta sostituisce i contenuti outputs flat con passaggi strutturati.

Prima (precedente)

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" }
    }
  ]
}

Dopo (nuovo 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" }
    }
  ]
}

Strumenti lato server

Gli strumenti lato server (come Ricerca Google o Esecuzione del codice) ora generano tipi di passaggi specifici nell'array steps. Mentre lo schema precedente restituiva queste operazioni come tipi di contenuti specifici all'interno dell'array outputs, il nuovo schema li sposta nell'array steps. L'esempio seguente utilizza Ricerca Google.

Prima (precedente)

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"
}

Dopo (nuovo 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

Lo streaming espone nuovi tipi di eventi:

Nuovi tipi di eventi

  • interaction.created
  • interaction.status_update: ora copre tutti gli stati del ciclo di vita, inclusi il completamento e gli errori (vedi gli stati di seguito)
  • step.start
  • step.delta
  • step.stop
Stati interaction.status_update
  • in_progress
  • active
  • completed
  • interrupted
  • requires_action
  • error

Tipi di eventi deprecati

I seguenti tipi di eventi precedenti vengono sostituiti dai nuovi eventi elencati sopra:

  • interaction.start → interaction.created
  • content.start → step.start
  • content.delta → step.delta
  • content.stop → step.stop
  • interaction.complete → interaction.status_update con status: "completed"
  • error → interaction.status_update con status: "error"
  • interaction.status_update → interaction.status_update (invariato, ma ora copre stati aggiuntivi)

Chiamate di funzioni in streaming: quando utilizzi lo streaming con le chiamate di funzioni, l'evento step.start fornisce il nome della funzione e gli eventi step.delta trasmettono gli argomenti come stringhe JSON parziali (utilizzando arguments_delta). Devi accumulare questi delta per ottenere gli argomenti completi. Questo è diverso dalle chiamate unarie in cui ricevi immediatamente l'oggetto della chiamata di funzione completo.

Esempi

Prima (precedente)

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}}
Dopo (nuovo 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

Cronologia delle conversazioni senza stato

Se gestisci manualmente la cronologia delle conversazioni sul lato client (caso d'uso senza stato), devi aggiornare il modo in cui concateni i turni precedenti.

  • Precedente: gli sviluppatori spesso raccoglievano l'array outputs dalle risposte e lo inviavano di nuovo nel campo input al turno successivo.
  • Nuovo schema: ora devi raccogliere l'array steps dalla risposta e passarlo nel campo input della richiesta successiva, aggiungendo il nuovo turno utente come passaggio user_input.

Configurazione del formato di output: modifiche a response_format

L'API aggiornata consolida tutti i controlli del formato di output in un campo response_format polimorfico unificato. In questo modo, la configurazione dell'output viene centralizzata al livello superiore e generation_config si concentra sul comportamento del modello (come temperatura, top_p e thinking).

Modifiche principali

  • L'API rimuove response_mime_type. Ora devi specificare il tipo MIME per ogni voce di formato all'interno di response_format.
  • response_format ora è un oggetto (o array) polimorfico. Ogni voce ha un discriminatore type (text, audio, image) e campi specifici per il tipo. Per richiedere più modalità di output, passa un array di voci di formato.
  • image_config viene spostato da generation_config a response_format. Ora devi specificare le impostazioni di output dell'immagine, come aspect_ratio e image_size in una voce response_format con "type": "image".

Output strutturato (JSON)

Il nuovo schema rimuove il campo response_mime_type. In alternativa, specifica il tipo MIME e lo schema JSON all'interno di un response_format oggetto con "type": "text".

Prima (precedente)

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" }
    }
  }
}

Dopo (nuovo 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" }
      }
    }
  }
}

Configurazione delle immagini

Il nuovo schema rimuove image_config da generation_config. Ora devi specificare le impostazioni di output dell'immagine in una voce response_format con "type": "image".

Prima (precedente)

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"
    }
  }
}

Dopo (nuovo 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
  }
}

Per richiedere più modalità di output (ad esempio, testo e audio insieme), passa un array di voci di formato a response_format anziché un singolo oggetto.

Come eseguire la migrazione al nuovo schema

Utenti dell'SDK

Esegui l'upgrade all'ultima versione dell'SDK (Python ≥1.76.0, JavaScript ≥1.53.0). L'SDK ti consente automaticamente di utilizzare il nuovo schema. Non sono necessarie modifiche al codice oltre all'aggiornamento della modalità di lettura delle risposte (vedi gli esempi sopra). Tieni presente che in queste versioni dell'SDK è supportato solo il nuovo schema. Le versioni precedenti dell'SDK (Python ≤1.73.1, JavaScript ≤1.50.1) continueranno a funzionare fino alla rimozione dello schema precedente il 6 giugno 2026.

Utenti dell'API REST

Aggiungi l'intestazione Api-Revision: 2026-05-20 alle richieste per attivare subito il nuovo schema. Dopo il 20 maggio, il nuovo schema diventerà quello predefinito per tutte le richieste. Puoi disattivarlo temporaneamente con Api-Revision: 2026-05-06 fino al 6 giugno, quando l'API rimuoverà definitivamente lo schema precedente.

Cronologia

Data Fase Utenti dell'SDK Utenti dell'API REST
6 maggio Attiva Nuova versione principale dell'SDK disponibile (Python ≥2.0.0, JS ≥2.0.0). Esegui l'upgrade per ottenere automaticamente il nuovo schema. Aggiungi l'intestazione Api-Revision: 2026-05-20 per attivare. Il valore predefinito rimane quello precedente.
20 maggio Inversione predefinita Non è necessaria alcuna azione se hai già eseguito l'upgrade. Gli SDK precedenti (Python 1.x.x, JS 1.x.x) continuano a funzionare, ma restituiscono risposte precedenti. Il nuovo schema è ora quello predefinito. Invia l'intestazione Api-Revision: 2026-05-06 per disattivare.
6 giugno Tramonto Le versioni dell'SDK 1.x.x per Python e JS non funzioneranno per le chiamate all'API Interactions. Schema precedente rimosso per l'API Interactions. Intestazione Api-Revision ignorata.

Elenco di controllo per la migrazione

Schema dei passaggi (steps)

  • Aggiorna il codice per leggere i contenuti della risposta dall'array steps anziché da outputs. Vedi gli esempi.
  • Verifica che il codice gestisca i tipi di passaggi user_input e model_output. Vedi gli esempi.
  • (Chiamata di funzione) Aggiorna il codice per trovare i passaggi function_call nell'array steps. Vedi gli esempi.
  • (Strumenti lato server) Aggiorna il codice per gestire i passaggi specifici dello strumento (ad es. google_search_call, google_search_result). Vedi gli esempi.
  • (Cronologia senza stato) Aggiorna la gestione della cronologia per passare l'array steps nel campo input della richiesta successiva. Vedi i dettagli.
  • (Solo streaming) Aggiorna il client per ascoltare i nuovi tipi di eventi SSE (interaction.created, step.delta e così via). Vedi gli esempi.

Configurazione del formato di output (response_format)

  • Sostituisci response_mime_type con un campo mime_type all'interno di response_format. Vedi gli esempi.
  • Inserisci lo schema JSON response_format esistente all'interno di un oggetto {"type": "text", "schema": ...}. Vedi gli esempi.
  • (Generazione di immagini) Sposta image_config da generation_config a una voce {"type": "image", ...} in response_format. Vedi gli esempi.
  • (Multimodale) Converti response_format da un singolo oggetto a un array quando richiedi più modalità di output.