Interactions API: Panduan migrasi perubahan yang dapat menyebabkan gangguan (Mei 2026)

Interactions API v1beta memperkenalkan perubahan yang dapat menyebabkan gangguan yang menata ulang bentuk API untuk mendukung kemampuan mendatang seperti pengarahan di tengah penerbangan dan panggilan alat asinkron. Halaman ini menjelaskan apa yang berubah dan memberikan contoh kode sebelum dan sesudah untuk membantu Anda melakukan migrasi. Ada dua kategori perubahan:

  1. Skema langkah: Array steps baru menggantikan array outputs, yang menyediakan linimasa terstruktur dari setiap giliran interaksi.
  2. Konfigurasi format output: `response_format` polimorfik baru mengonsolidasikan semua kontrol format output dan menghapus `response_mime_type`.response_formatresponse_mime_type

Ikuti langkah-langkah di Cara melakukan migrasi ke skema baru untuk memperbarui integrasi Anda.

Perubahan inti: outputs menjadi steps

Skema baru menggantikan array outputs dengan array steps.

  • Lama: Respons menampilkan array outputs datar yang hanya berisi konten yang dihasilkan model.
  • Skema baru: Respons menampilkan array steps yang menyertakan input pengguna yang diulang dan output model, sehingga memberikan linimasa lengkap dari giliran interaksi.

Respons unary (non-streaming) mengulang input Anda sebagai langkah pertama dalam array steps. Respons streaming melewati langkah input dan hanya memancarkan delta konten yang dihasilkan.

Input/output dasar (unary)

Sebelum (lama)

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

Setelah (skema baru)

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

Panggilan fungsi

Struktur permintaan tetap tidak berubah, tetapi respons menggantikan konten outputs datar dengan langkah-langkah terstruktur.

Sebelum (lama)

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

Setelah (skema baru)

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

Alat sisi server

Alat sisi server (seperti Google Penelusuran atau Eksekusi Kode) kini menghasilkan jenis langkah tertentu dalam array steps. Meskipun skema lama menampilkan operasi ini sebagai jenis konten tertentu dalam array outputs, skema baru memindahkannya ke array steps. Contoh berikut menggunakan Google Penelusuran.

Sebelum (lama)

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

Setelah (skema baru)

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 menampilkan jenis peristiwa baru:

Jenis peristiwa baru

  • interaction.created
  • interaction.status_update — kini mencakup semua status siklus proses, termasuk penyelesaian dan error (lihat status di bawah)
  • step.start
  • step.delta
  • step.stop
Status interaction.status_update
  • in_progress
  • active
  • completed
  • interrupted
  • requires_action
  • error

Jenis peristiwa yang tidak digunakan lagi

Jenis peristiwa lama berikut diganti dengan peristiwa baru yang tercantum di atas:

  • interaction.start → interaction.created
  • content.start → step.start
  • content.delta → step.delta
  • content.stop → step.stop
  • interaction.complete → interaction.status_update dengan status: "completed"
  • error → interaction.status_update dengan status: "error"
  • interaction.status_update → interaction.status_update (tidak berubah, tetapi kini mencakup status tambahan)

Panggilan fungsi streaming: Saat Anda menggunakan streaming dengan panggilan fungsi, peristiwa step.start akan menampilkan nama fungsi, dan peristiwa step.delta akan melakukan streaming argumen sebagai string JSON parsial (menggunakan arguments_delta). Anda harus mengakumulasikan delta ini untuk mendapatkan argumen lengkap. Hal ini berbeda dengan panggilan unary yang menerima objek panggilan fungsi lengkap sekaligus.

Contoh

Sebelum (Lama)

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}}
Setelah (Skema Baru)

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

Histori Percakapan Tanpa Status

Jika Anda mengelola histori percakapan secara manual di sisi klien (kasus penggunaan tanpa status), Anda harus memperbarui cara Anda menggabungkan giliran sebelumnya.

  • Lama: Developer sering mengumpulkan array outputs dari respons dan mengirimkannya kembali di kolom input pada giliran berikutnya.
  • Skema baru: Anda kini harus mengumpulkan array steps dari respons dan meneruskannya di kolom input permintaan berikutnya, dengan menambahkan giliran pengguna baru sebagai langkah user_input.

Konfigurasi format output: Perubahan response_format

API yang diperbarui mengonsolidasikan semua kontrol format output ke dalam kolom response_format polimorfik terpadu. Hal ini memusatkan konfigurasi output di tingkat atas dan membuat generation_config berfokus pada perilaku model (seperti temperatur, top_p, dan pemikiran).

Perubahan penting

  • API menghapus response_mime_type. Anda kini menentukan jenis MIME per entri format di dalam response_format.
  • response_format kini merupakan objek (atau array) polimorfik. Setiap entri memiliki diskriminator type (text, audio, image) dan kolom khusus jenis. Untuk meminta beberapa modalitas output, teruskan array entri format.
  • image_config dipindahkan dari generation_config ke response_format. Anda kini menentukan setelan output gambar seperti aspect_ratio dan image_size dalam entri response_format dengan "type": "image".

Output terstruktur (JSON)

Skema baru menghapus kolom response_mime_type. Sebagai gantinya, tentukan jenis MIME dan skema JSON di dalam objek response_format dengan "type": "text".

Sebelum (lama)

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

Setelah (skema baru)

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

Konfigurasi gambar

Skema baru menghapus image_config dari generation_config. Anda kini menentukan setelan output gambar dalam entri response_format dengan "type": "image".

Sebelum (lama)

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

Setelah (skema baru)

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

Untuk meminta beberapa modalitas output (misalnya, teks dan audio bersama-sama), teruskan array entri format ke response_format, bukan satu objek.

Cara melakukan migrasi ke skema baru

Pengguna SDK

Upgrade ke versi SDK terbaru (Python ≥1.76.0, JavaScript ≥1.53.0). SDK otomatis mengikutsertakan Anda ke skema baru — tidak ada perubahan kode yang diperlukan selain memperbarui cara Anda membaca respons (lihat contoh di atas). Perhatikan bahwa hanya skema baru yang didukung dalam versi SDK ini. Versi SDK lama (Python ≤1.73.1, JavaScript ≤1.50.1) akan terus berfungsi hingga skema lama dihapus pada 6 Juni 2026.

Pengguna REST API

Tambahkan header Api-Revision: 2026-05-20 ke permintaan Anda untuk ikut serta ke skema baru sekarang. Setelah 20 Mei, skema baru akan menjadi default untuk semua permintaan. Anda dapat memilih tidak ikut serta untuk sementara dengan Api-Revision: 2026-05-06 hingga 6 Juni, saat API menghapus skema lama secara permanen.

Linimasa

Tanggal Fase Pengguna SDK Pengguna REST API
6 Mei Ikut serta Versi SDK utama baru tersedia (Python ≥2.0.0, JS ≥2.0.0). Upgrade untuk mendapatkan skema baru secara otomatis. Tambahkan header Api-Revision: 2026-05-20 untuk ikut serta. Default tetap lama.
20 Mei Perubahan default Tidak ada tindakan yang diperlukan jika sudah diupgrade. SDK lama (Python 1.x.x, JS 1.x.x) masih berfungsi, tetapi menampilkan respons lama. Skema baru kini menjadi default. Kirim header Api-Revision: 2026-05-06 untuk memilih tidak ikut serta.
6 Juni Senja Versi SDK 1.x.x untuk Python dan JS akan rusak untuk panggilan Interactions API. Skema lama dihapus untuk Interactions API. Header Api-Revision diabaikan.

Checklist Migrasi

Skema langkah (steps)

  • Perbarui kode untuk membaca konten respons dari array steps, bukan outputs. Lihat contoh..
  • Pastikan kode Anda menangani jenis langkah user_input dan model_output. Lihat contoh..
  • (Panggilan Fungsi) Perbarui kode untuk menemukan langkah function_call dalam array steps. Lihat contoh..
  • (Alat Sisi Server) Perbarui kode untuk menangani langkah-langkah khusus alat (misalnya, google_search_call, google_search_result). Lihat contoh.
  • (Histori Tanpa Status) Perbarui pengelolaan histori untuk meneruskan array steps di kolom input permintaan berikutnya. Lihat detailnya.
  • (Streaming saja) Perbarui klien untuk memproses jenis peristiwa SSE baru (interaction.created, step.delta, dll.). Lihat contoh.

Konfigurasi format output (response_format)

  • Ganti response_mime_type dengan kolom mime_type di dalam response_format. Lihat contoh.
  • Gabungkan skema JSON response_format yang ada di dalam objek {"type": "text", "schema": ...}. Lihat contoh.
  • (Pembuatan Gambar) Pindahkan image_config dari generation_config ke entri {"type": "image", ...} di response_format. Lihat contoh.
  • (Multimodal) Konversi response_format dari satu objek ke array saat meminta beberapa modalitas output.