API de Interactions: Guía de migración de cambios rotundos (mayo de 2026)

La API de Interactions v1beta presenta cambios rotundos que reestructuran la forma de la API para admitir capacidades futuras, como la dirección en vuelo y las llamadas a herramientas asíncronas. En esta página, se explica qué cambia y se proporcionan ejemplos de código antes y después para ayudarte con la migración. Hay dos categorías de cambios:

  1. Esquema de pasos: Un nuevo array steps reemplaza el array outputs y proporciona un cronograma estructurado de cada turno de interacción.
  2. Configuración del formato de salida: Un nuevo polimórfico response_format consolida todos los controles de formato de salida y quita response_mime_type.

Sigue los pasos que se indican en Cómo migrar al esquema nuevo para actualizar tu integración.

Cambio principal: outputs a steps

El esquema nuevo reemplaza el array outputs por un array steps.

  • Heredado: Las respuestas mostraban un array outputs plano que contenía solo el contenido generado del modelo.
  • Esquema nuevo: Las respuestas muestran un array steps que incluye las entradas de usuario repetidas y los resultados del modelo, lo que proporciona un cronograma completo del turno de interacción.

Las respuestas unarias (sin transmisión) repiten tu entrada como el primer paso en el array steps. Las respuestas de transmisión omiten el paso de entrada y solo emiten deltas de contenido generado.

Entrada y salida básicas (unarias)

Antes (heredado)

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

Después (esquema nuevo)

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

Llamada a función

La estructura de la solicitud permanece sin cambios, pero la respuesta reemplaza el contenido outputs plano por pasos estructurados.

Antes (heredado)

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

Después (esquema nuevo)

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

Herramientas del servidor

Las herramientas del lado del servidor (como la Búsqueda de Google o la ejecución de código) ahora generan tipos de pasos específicos en el array steps. Si bien el esquema heredado mostraba estas operaciones como tipos de contenido específicos dentro del array outputs, el esquema nuevo los mueve al array steps. En los siguientes ejemplos, se usa la Búsqueda de Google.

Antes (heredado)

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

Después (esquema nuevo)

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

Transmisión

La transmisión expone nuevos tipos de eventos:

Tipos de eventos nuevos

  • interaction.created
  • interaction.status_update ahora abarca todos los estados del ciclo de vida, incluidos la finalización y los errores (consulta los estados a continuación)
  • step.start
  • step.delta
  • step.stop
Estados interaction.status_update
  • in_progress
  • active
  • completed
  • interrupted
  • requires_action
  • error

Tipos de eventos obsoletos

Los siguientes tipos de eventos heredados se reemplazan por los eventos nuevos que se mencionan más arriba:

  • 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 (sin cambios, pero ahora abarca estados adicionales)

Llamadas a funciones de transmisión: Cuando usas la transmisión con la llamada a función, el evento step.start entrega el nombre de la función y los eventos step.delta transmiten los argumentos como cadenas JSON parciales (con arguments_delta). Debes acumular estos deltas para obtener los argumentos completos. Esto difiere de las llamadas unarias en las que recibes el objeto de llamada a función completo de inmediato.

Ejemplos

Antes (heredado)

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}}
Después (esquema nuevo)

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

Historial de conversaciones sin estado

Si administras el historial de conversaciones de forma manual en el cliente (caso de uso sin estado), debes actualizar la forma en que encadenas los turnos anteriores.

  • Heredado: Los desarrolladores solían recopilar el array outputs de las respuestas y enviarlo de vuelta en el campo input en el siguiente turno.
  • Esquema nuevo: Ahora debes recopilar el array steps de la respuesta y pasarlo al campo input de la siguiente solicitud, y agregar tu nuevo turno de usuario como un paso user_input.

Configuración del formato de resultado: cambios en response_format

La API actualizada consolida todos los controles de formato de salida en un campo response_format unificado y polimórfico. Esto centraliza la configuración de salida en el nivel superior y mantiene generation_config enfocada en el comportamiento del modelo (como la temperatura, top_p y el pensamiento).

Cambios clave

  • La API quita response_mime_type. Ahora especificas el tipo de MIME por entrada de formato dentro de response_format.
  • response_format ahora es un objeto (o array) polimórfico. Cada entrada tiene un discriminador type (text, audio, image) y campos específicos del tipo. Para solicitar varias modalidades de salida, pasa un array de entradas de formato.
  • image_config se mueve de generation_config a response_format. Ahora especificas la configuración de salida de la imagen, como aspect_ratio y image_size en una entrada response_format con "type": "image".

Salida estructurada (JSON)

El esquema nuevo quita el campo response_mime_type. En su lugar, especifica el tipo de MIME y el esquema JSON dentro de un response_format objeto con "type": "text".

Antes (heredado)

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

Después (esquema nuevo)

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

Configuración de la imagen

El esquema nuevo quita image_config de generation_config. Ahora especificas la configuración de salida de la imagen en una entrada response_format con "type": "image".

Antes (heredado)

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

Después (esquema nuevo)

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

Para solicitar varias modalidades de salida (por ejemplo, texto y audio juntos), pasa un array de entradas de formato a response_format en lugar de un solo objeto.

Cómo migrar al esquema nuevo

Usuarios del SDK

Actualiza a la versión más reciente del SDK (Python ≥1.76.0, JavaScript ≥1.53.0). El SDK te habilita automáticamente para el esquema nuevo. No se necesitan cambios sin código más allá de actualizar la forma en que lees las respuestas (consulta los ejemplos anteriores). Ten en cuenta que solo se admite el esquema nuevo en estas versiones del SDK. Las versiones anteriores del SDK (Python ≤1.73.1, JavaScript ≤1.50.1) seguirán funcionando hasta que se quite el esquema heredado el 6 de junio de 2026.

Usuarios de la API de REST

Agrega el encabezado Api-Revision: 2026-05-20 a tus solicitudes para habilitar el esquema nuevo ahora. Después del 20 de mayo, el esquema nuevo se convertirá en el predeterminado para todas las solicitudes. Puedes inhabilitarlo temporalmente con Api-Revision: 2026-05-06 hasta el 6 de junio, cuando la API quite de forma permanente el esquema heredado.

Cronograma

Fecha Fase Usuarios del SDK Usuarios de la API de REST
6 de mayo Habilitar Nueva versión principal del SDK disponible (Python ≥2.0.0, JS ≥2.0.0). Actualiza para obtener el esquema nuevo automáticamente. Agrega el encabezado Api-Revision: 2026-05-20 para habilitar. El valor predeterminado sigue siendo heredado.
20 de mayo Cambio predeterminado No es necesario realizar ninguna acción si ya se actualizó. Los SDK más antiguos (Python 1.x.x, JS 1.x.x) aún funcionan, pero muestran respuestas heredadas. El esquema nuevo ahora es el predeterminado. Envía el encabezado Api-Revision: 2026-05-06 para inhabilitar.
6 de junio Atardecer Las versiones 1.x.x del SDK para Python y JS dejarán de funcionar para las llamadas a la API de Interactions. Se quitó el esquema heredado para la API de Interactions. Se ignoró el encabezado Api-Revision.

Lista de tareas para la migración

Esquema de pasos (steps)

  • Actualiza el código para leer el contenido de la respuesta del array steps en lugar de outputs. Consulta los ejemplos.
  • Verifica que tu código controle los tipos de pasos user_input y model_output. Consulta los ejemplos.
  • (Llamada a función) Actualiza el código para encontrar pasos function_call en el array steps. Consulta los ejemplos.
  • (Herramientas del servidor) Actualiza el código para controlar los pasos específicos de la herramienta (p.ej., google_search_call, google_search_result). Consulta los ejemplos.
  • (Historial sin estado) Actualiza la administración del historial para pasar el array steps en el campo input de la siguiente solicitud. Consulta los detalles.
  • (Solo transmisión) Actualiza el cliente para que escuche los nuevos tipos de eventos SSE (interaction.created, step.delta, etc.). Consulta los ejemplos.

Configuración del formato de salida (response_format)

  • Reemplaza response_mime_type por un campo mime_type dentro de response_format. Consulta los ejemplos.
  • Encapsula tu esquema JSON response_format existente dentro de un objeto {"type": "text", "schema": ...}. Consulta los ejemplos.
  • (Generación de imágenes) Mueve image_config de generation_config a una entrada {"type": "image", ...} en response_format. Consulta los ejemplos.
  • (Multimodal) Convierte response_format de un solo objeto a un array cuando solicites varias modalidades de salida.