Etkileşimler API'si: Önemli değişiklikler için taşıma kılavuzu (Mayıs 2026)

v1beta Interactions API, API şeklini yeniden yapılandırarak uçuş ortasında yönlendirme ve eşzamansız araç çağrıları gibi gelecekteki özellikleri desteklemek için API'de uyumluluğu bozan değişiklikler yapıyor. Bu sayfada, nelerin değiştiği açıklanmakta ve geçiş yapmanıza yardımcı olmak için öncesi ve sonrası kod örnekleri verilmektedir. İki değişiklik kategorisi vardır:

  1. Adımlar şeması: steps dizisi, outputs dizisinin yerini alarak her etkileşim dönüşünün yapılandırılmış bir zaman çizelgesini sunar.
  2. Çıkış biçimi yapılandırması: Yeni bir polimorfik response_format, tüm çıkış biçimi kontrollerini birleştirir ve kaldırır response_mime_type.

Entegrasyonunuzu güncellemek için Yeni şemaya nasıl geçilir? başlıklı makaledeki adımları uygulayın.

Temel değişiklik: outputs ile steps arasındaki fark

Yeni şema, outputs dizisini steps dizisiyle değiştirir.

  • Eski: Yanıtlarda yalnızca modelin oluşturduğu içeriği içeren düz bir outputs dizisi döndürülüyordu.
  • Yeni şema: Yanıtlarda, hem tekrarlanan kullanıcı girişlerini hem de model çıkışlarını içeren bir steps dizisi döndürülür. Böylece, etkileşim dönüşünün tam zaman çizelgesi sağlanır.

Tekli (aktarım olmayan) yanıtlar, girişinizi steps dizisindeki ilk adım olarak tekrar eder. Akış şeklinde gösterilen yanıtlarda giriş adımı atlanır ve yalnızca oluşturulan içerik farklılıkları verilir.

Temel giriş/çıkış (tekli)

Önce (eski)

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

Sonra (yeni şema)

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

İşlev çağırma

İstek yapısı değişmeden kalır ancak yanıt, düz outputs içeriği yapılandırılmış adımlarla değiştirir.

Önce (eski)

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

Sonra (yeni şema)

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

Sunucu tarafı araçlar

Sunucu tarafı araçlar (ör. Google Arama veya Kod Yürütme) artık steps dizisinde belirli adım türleri oluşturuyor. Eski şema bu işlemleri outputs dizisindeki belirli içerik türleri olarak döndürürken yeni şema bunları steps dizisine taşır. Aşağıdaki örneklerde Google Arama kullanılmaktadır.

Önce (eski)

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

Sonra (yeni şema)

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

Canlı Yayın

Yayın, yeni etkinlik türleri sunar:

Yeni etkinlik türleri

  • interaction.created
  • interaction.status_update — artık tamamlanma ve hatalar dahil olmak üzere tüm yaşam döngüsü durumlarını kapsıyor (aşağıdaki durumları inceleyin)
  • step.start
  • step.delta
  • step.stop
interaction.status_update durumlar
  • in_progress
  • active
  • completed
  • interrupted
  • requires_action
  • error

Desteği sonlandırılmış etkinlik türleri

Aşağıdaki eski etkinlik türlerinin yerini yukarıda listelenen yeni etkinlikler almıştır:

  • interaction.start → interaction.created
  • content.start → step.start
  • content.delta → step.delta
  • content.stop → step.stop
  • interaction.complete → status: "completed" ile interaction.status_update
  • error → status: "error" ile interaction.status_update
  • interaction.status_update → interaction.status_update (değişmedi ancak artık ek eyaletleri kapsıyor)

Akışlı işlev çağrıları: İşlev çağrısıyla akışı kullandığınızda step.start etkinliği işlev adını, step.delta etkinlikleri ise bağımsız değişkenleri kısmi JSON dizeleri olarak (arguments_delta kullanarak) aktarır. Tam bağımsız değişkenleri almak için bu deltaları biriktirmeniz gerekir. Bu, işlev çağrısı nesnesinin tamamını tek seferde aldığınız tekli çağrılardan farklıdır.

Örnekler

Önce (Eski)

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}}
Sonra (Yeni Şema)

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

Durum Bilgisiz Görüşme Geçmişi

İstemci tarafında (durum bilgisiz kullanım alanı) görüşme geçmişini manuel olarak yönetiyorsanız önceki dönüşleri nasıl bir araya getirdiğinizi güncellemeniz gerekir.

  • Eski: Geliştiriciler genellikle yanıtlardan outputs dizisini toplar ve bir sonraki dönüşte input alanında geri gönderirdi.
  • Yeni şema: Artık yanıttan steps dizisini toplamanız ve bunu sonraki isteğin input alanına iletmeniz, yeni kullanıcı dönüşünüzü user_input adımı olarak eklemeniz gerekir.

Çıkış biçimi yapılandırması: response_format değişiklik

Güncellenen API, tüm çıkış biçimi kontrollerini birleşik ve polimorfik bir response_format alanında birleştirir. Bu, çıkış yapılandırmasını üst düzeyde merkezileştirir ve generation_config'nın model davranışına (ör. sıcaklık, top_p ve düşünme) odaklanmasını sağlar.

Önemli değişiklikler

  • API, response_mime_type öğesini kaldırır. Artık response_format içindeki biçim girişi başına MIME türünü belirtiyorsunuz.
  • response_format artık polimorfik bir nesne (veya dizi). Her girişin bir type ayrıştırıcısı (text, audio, image) ve türe özgü alanları vardır. Birden fazla çıkış biçimi isteğinde bulunmak için bir biçim girişleri dizisi iletin.
  • image_config, generation_config kuruluş biriminden response_format kuruluş birimine taşınıyor. Artık aspect_ratio ve image_size gibi görüntü çıkışı ayarlarını "type": "image" ile birlikte response_format girişinde belirtiyorsunuz.

Yapılandırılmış çıkış (JSON)

Yeni şema, response_mime_type alanını kaldırır. Bunun yerine, MIME türünü ve JSON şemasını response_format nesnesinin içinde "type": "text" ile belirtin.

Önce (eski)

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

Sonra (yeni şema)

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

Resim yapılandırması

Yeni şema, image_config öğesini generation_config öğesinden kaldırır. Artık görüntü çıkışı ayarlarını response_format ile "type": "image" girişinde belirtiyorsunuz.

Önce (eski)

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

Sonra (yeni şema)

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

Birden fazla çıkış biçimi (ör. metin ve ses birlikte) istemek için tek bir nesne yerine response_format işlevine bir biçim girişleri dizisi iletin.

Yeni şemaya nasıl geçilir?

SDK kullanıcıları

En son SDK sürümüne (Python ≥1.76.0, JavaScript ≥1.53.0) yükseltin. SDK, yanıtları okuma şeklinizi güncellemenin dışında herhangi bir kod değişikliği yapmanıza gerek kalmadan sizi otomatik olarak yeni şemaya kaydeder (yukarıdaki örneklere bakın). Bu SDK sürümlerinde yalnızca yeni şemanın desteklendiğini unutmayın. Eski SDK sürümleri (Python ≤1.73.1, JavaScript ≤1.50.1), eski şema 6 Haziran 2026'da kaldırılana kadar çalışmaya devam edecek.

REST API kullanıcıları

Yeni şemayı hemen etkinleştirmek için isteklerinize Api-Revision: 2026-05-20 üstbilgisini ekleyin. 20 Mayıs'tan sonra yeni şema, tüm istekler için varsayılan hale gelir. API, eski şemayı kalıcı olarak kaldırana kadar 6 Haziran'a kadar Api-Revision: 2026-05-06 ile geçici olarak kapsam dışında kalabilirsiniz.

Zaman çizelgesi

Tarih Faz SDK kullanıcıları REST API kullanıcıları
6 Mayıs Etkinleştir Yeni ana SDK sürümü kullanıma sunuldu (Python ≥2.0.0, JS ≥2.0.0). Yeni şemayı otomatik olarak almak için yükseltin. Etkinleştirmek için Api-Revision: 2026-05-20 üstbilgisini ekleyin. Varsayılan olarak eski sürüm kalır.
20 Mayıs Varsayılan çevirme Daha önce yükselttiyseniz herhangi bir işlem yapmanız gerekmez. Eski SDK'lar (Python 1.x.x, JS 1.x.x) çalışmaya devam eder ancak eski yanıtlar döndürür. Yeni şema artık varsayılan olarak ayarlanmıştır. Devre dışı bırakmak için Api-Revision: 2026-05-06 üstbilgisini gönderin.
6 Haziran Gün batımı Python ve JS için 1.x.x SDK sürümleri, Etkileşimler API'si çağrıları için çalışmaz. Etkileşimler API'si için eski şema kaldırıldı. Api-Revision üstbilgisi yoksayıldı.

Taşıma Denetim Listesi

Adımlar şeması (steps)

  • Kodu, yanıt içeriğini outputs yerine steps dizisinden okuyacak şekilde güncelleyin. Örnekleri inceleyin.
  • Kodunuzun hem user_input hem de model_output adım türlerini işlediğini doğrulayın. Örnekleri inceleyin.
  • (İşlev Çağırma) steps dizisindeki function_call adımlarını bulmak için kodu güncelleyin. Örnekleri inceleyin.
  • (Sunucu Tarafı Araçlar) Kodu, araca özgü adımları (ör. google_search_call, google_search_result) işleyecek şekilde güncelleyin. Örnekleri inceleyin.
  • (Durum Bilgisiz Geçmiş) Geçmiş yönetimini, sonraki isteğin input alanında steps dizisini iletecek şekilde güncelleyin. Ayrıntıları göster'i tıklayın.
  • (Yalnızca akış) İstemciyi, yeni SSE etkinlik türlerini (interaction.created, step.delta vb.) dinleyecek şekilde güncelleyin. Örnekleri inceleyin.

Çıkış biçimi yapılandırması (response_format)

  • response_mime_type değerini response_format içindeki bir mime_type alanı ile değiştirin. Örnekleri inceleyin.
  • Mevcut response_format JSON şemanızı {"type": "text", "schema": ...} nesnesi içine alın. Örnekleri inceleyin.
  • (Görüntü Üretme) image_config, generation_config öğesinden response_format içindeki {"type": "image", ...} girişine taşındı. Örnekleri inceleyin.
  • (Çok formatlı) Birden fazla çıkış biçimi istenirken response_format öğesini tek bir nesneden diziye dönüştürün.