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

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

  1. Schema dei passaggi: un nuovo array steps sostituisce l'array outputs, fornendo una cronologia 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.

  • Legacy: le risposte restituivano un array outputs semplice contenente solo i contenuti generati dal modello.
  • Nuovo schema: le risposte restituiscono un array steps contenente passaggi strutturati con discriminatori di tipo.

POST /interactions restituisce solo i passaggi di output. GET /interactions/{id} restituisce la cronologia completa dei passaggi, incluso il passaggio user_input iniziale.

Input/output di base (unario)

Prima (legacy)

Python

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

# Response access
print(interaction.outputs[-1].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[-1].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Tell me a joke."
  }'

// POST Response
{
  "id": "int_123",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

// GET /v1beta/interactions/int_123 (returns full timeline including input)
{
  "id": "int_123",
  "steps": [
    {
      "type": "user_input",
      "content": [
        { "type": "text", "text": "Tell me a joke." }
      ]
    },
    {
      "type": "model_output",
      "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 con passaggi strutturati.

Prima (legacy)

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

// POST Response
{
  "id": "int_001",
  "status": "requires_action",
  "steps": [
    {
      "type": "thought",
      "summary": [{
        "type": "text",
        "text": "I need to check the weather in Boston..."
      }],
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]
}

Strumenti lato server

Gli strumenti lato server (come la Ricerca Google o l'esecuzione di codice) ora producono 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 le sposta nell'array steps. Gli esempi riportati di seguito utilizzano la Ricerca Google.

Prima (legacy)

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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Who won the last Super Bowl?",
    "tools": [
      { "type": "google_search" }
    ]
  }'

// POST Response
{
  "id": "int_456",
  "steps": [
    {
      "type": "google_search_call",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] },
      "signature": "abc123..."
    },
    {
      "type": "google_search_result",
      "call_id": "gs_1",
      "result": {
        "search_suggestions": "<div>...</div>"
      },
      "signature": "abc123..."
    },
    {
      "type": "model_output",
      "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.completed
  • interaction.in_progress
  • interaction.requires_action
  • step.start
  • step.delta
  • step.stop

Tipi di eventi deprecati

I seguenti tipi di eventi legacy 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.completed
  • interaction.status_update → sostituito da interaction.in_progress, interaction.requires_action e così via.

Chiamate di funzione in streaming: quando utilizzi lo streaming con le chiamate di funzione, 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. Ciò è diverso dalle chiamate unarie in cui ricevi l'oggetto di chiamata di funzione completo contemporaneamente.

Esempi

Prima (legacy)

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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

 # Opt-in needed before May 26th
 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
   -H "Content-Type: application/json" \
   -H "Accept: text/event-stream" \
   -H "Api-Revision: 2026-05-20" \
   -d '{
     "model": "gemini-3-flash-preview",
     "input": "Tell me a story.",
     "stream": true
   }'

 // Response (SSE Lines)
 // event: interaction.created
 // data: {"interaction": {"id": "int_xyz", "status": "in_progress", "object": "interaction", "model": "gemini-3-flash-preview"}, "event_type": "interaction.created"}
 //
 // event: interaction.in_progress
 // data: {"interaction_id": "int_xyz", "event_type": "interaction.in_progress"}
 //
 // event: step.start
 // data: {"index": 0, "step": {"type": "thought", "signature": "abc123..."}, "event_type": "step.start"}
 //
 // event: step.stop
 // data: {"index": 0, "event_type": "step.stop"}
 //
 // event: step.start
 // data: {"index": 1, "step": {"content": [{"text": "Once upon", "type": "text"}], "type": "model_output"}, "event_type": "step.start"}
 //
 // event: step.delta
 // data: {"index": 1, "delta": {"text": " a time...", "type": "text"}, "event_type": "step.delta"}
 //
 // event: step.stop
 // data: {"type": "step.stop", "index": 1, "status": "done"}
 //
 // event: interaction.completed
 // data: {"type": "interaction.completed", "interaction": {"id": "int_xyz", "status": "completed", "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}}} // NEW: Dedicated completion event

Cronologia conversazione stateless

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

  • Legacy: 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 dell'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 a livello superiore e generation_config si concentra sul comportamento del modello (ad esempio temperatura, top_p e ragionamento).

Modifiche principali

  • L'API rimuove response_mime_type. Ora specifica 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, trasmetti un array di voci di formato.
  • image_config si sposta da generation_config a response_format. Ora puoi 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. Specifica invece il tipo MIME e lo schema JSON all'interno di un oggetto response_format con "type": "text".

Prima (legacy)

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[-1].text)

JavaScript

const interaction = await 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' }
        }
    },
});

console.log(interaction.outputs[-1].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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.',
    // 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' }
            }
        }
    },
});

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

REST

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Summarize this article.",
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" }
        }
      }
    }
  }'

Configurazione delle immagini

Il nuovo schema rimuove image_config da generation_config. Ora puoi specificare le impostazioni di output delle immagini in una voce response_format con "type": "image".

Prima (legacy)

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.',
    generation_config: {
        image_config: {
            aspect_ratio: '1:1',
            image_size: '1K'
        }
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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",
        "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.',
    // image_config is removed from generation_config — use response_format
    response_format: {
        type: 'image',
        mime_type: 'image/jpeg',
        aspect_ratio: '1:1',
        image_size: '1K'
    },
});

REST

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Generate an image of a sunset over the ocean.",
    "response_format": {
      "type": "image",
      "mime_type": "image/jpeg",
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }'

Per richiedere più modalità di output (ad esempio, testo e audio insieme), trasmetti 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 ≥2.0.0, JavaScript ≥2.0.0). L'SDK ti registra automaticamente al nuovo schema. Non sono necessarie modifiche al codice, se non l'aggiornamento del modo in cui leggi le 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.x.x, JavaScript 1.x.x) continueranno a funzionare finché lo schema legacy non verrà rimosso l'8 giugno 2026.

Utenti API REST

Aggiungi l'intestazione Api-Revision: 2026-05-20 alle tue richieste per attivare il nuovo schema ora. Dopo il 26 maggio, il nuovo schema diventa quello predefinito per tutte le richieste. Puoi disattivare temporaneamente l'API con Api-Revision: 2026-05-07 fino all'8 giugno, quando l'API rimuoverà definitivamente lo schema legacy.

Cronologia

Data Fase Utenti dell'SDK Utenti API REST
7 maggio Attiva Nuova versione 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 la funzionalità. Il valore predefinito rimane quello precedente.
26 maggio Capovolgimento predefinito Se hai già eseguito l'upgrade, non è necessaria alcuna azione. Gli SDK precedenti (Python 1.x.x, JS 1.x.x) funzionano ancora, ma restituiscono risposte legacy. Il nuovo schema è ora quello predefinito. Invia l'intestazione Api-Revision: 2026-05-07 per disattivare la funzionalità.
8 giugno Tramonto Le versioni 1.x.x degli SDK 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 Passi (steps)

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

Configurazione del formato di output (response_format)

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