API i Ndërveprimeve: Udhëzues për migrimin e ndryshimeve të rëndësishme (maj 2026)

API-ja v1beta Interactions po prezanton ndryshime të rëndësishme që ristrukturojnë formën e API-t për të mbështetur aftësitë e ardhshme si drejtimi në mes të fluturimit dhe thirrjet asinkrone të mjeteve. Kjo faqe shpjegon se çfarë po ndryshon dhe ofron shembuj të kodit para dhe pas për t'ju ndihmuar të migroni. Ekzistojnë dy kategori ndryshimesh:

  1. Skema e hapave : Një varg i ri steps zëvendëson vargun e outputs , duke ofruar një afat kohor të strukturuar për çdo kthesë të ndërveprimit.
  2. Konfigurimi i formatit të daljes : Një response_format i ri polimorfik konsolidon të gjitha kontrollet e formatit të daljes dhe heq response_mime_type .

Ndiqni hapat në Si të migroni në skemën e re për të përditësuar integrimin tuaj.

Ndryshimi thelbësor: outputs në steps

Skema e re zëvendëson vargun e outputs me një varg steps .

  • Trashëgimia : Përgjigjet kthyen një matricë të sheshtë outputs që përmbante vetëm përmbajtjen e gjeneruar të modelit.
  • Skemë e re : Përgjigjet kthejnë një varg steps që përfshin si hyrjet e përsëritura të përdoruesit ashtu edhe daljet e modelit, duke ofruar një kronologji të plotë të kthesës së ndërveprimit.

Përgjigjet unare (jo-transmetuese) i bëjnë jehonë të dhënave tuaja hyrëse si hapi i parë në vargun e steps . Përgjigjet transmetuese anashkalojnë hapin e të dhënave hyrëse dhe emetojnë vetëm delta me përmbajtje të gjeneruar.

Hyrje/dalje bazë (unare)

Përpara (trashëgimi)

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);

PUSHTIM 

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

Pas (skema e re)

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);

PUSHTIM 

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

Thirrja e funksionit

Struktura e kërkesës mbetet e pandryshuar, por përgjigjja zëvendëson përmbajtjen e outputs të sheshta me hapa të strukturuar.

Përpara (trashëgimi)

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)}`);
    }
}

PUSHTIM 

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

Pas (skema e re)

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)}`);
    }
}

PUSHTIM 

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

Mjete nga ana e serverit

Mjetet në anën e serverit (si Google Search ose Code Execution) tani japin lloje specifike hapash në vargun e steps . Ndërsa skema e trashëguar i ktheu këto operacione si lloje specifike përmbajtjeje brenda vargut të outputs , skema e re i zhvendos ato në vargun e steps . Shembujt e mëposhtëm përdorin Google Search.

Përpara (trashëgimi)

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}`);
    }
}

PUSHTIM 

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

Pas (skema e re)

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}`);
    }
}

PUSHTIM 

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

Transmetim

Transmetimi ekspozon lloje të reja ngjarjesh:

Llojet e reja të ngjarjeve

  • interaction.created
  • interaction.status_update — tani mbulon të gjitha gjendjet e ciklit jetësor, duke përfshirë përfundimin dhe gabimet (shih statuset më poshtë)
  • step.start
  • step.delta
  • step.stop
statuset interaction.status_update
  • in_progress
  • active
  • completed
  • interrupted
  • requires_action
  • error

Llojet e ngjarjeve të vjetruara

Llojet e mëposhtme të ngjarjeve të trashëguara zëvendësohen nga ngjarjet e reja të listuara më sipër:

  • interaction.start → interaction.created
  • content.start → step.start
  • content.delta → step.delta
  • content.stop → step.stop
  • interaction.complete → interaction.status_update me status: "completed"
  • error → interaction.status_update me status: "error"
  • interaction.status_update → interaction.status_update (i pandryshuar, por tani mbulon gjendje shtesë)

Thirrjet e funksioneve me transmetim : Kur përdorni transmetimin me thirrjen e funksionit, ngjarja step.start jep emrin e funksionit dhe ngjarjet step.delta i transmetojnë argumentet si vargje të pjesshme JSON (duke përdorur arguments_delta ). Ju duhet të grumbulloni këto delta për të marrë argumentet e plota. Kjo ndryshon nga thirrjet unare ku merrni objektin e plotë të thirrjes së funksionit menjëherë.

Shembuj

Para (Trashëgimi)

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

PUSHTIM 

// 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}}
Pas (Skema e Re)

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

PUSHTIM 

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

Historiku i bisedave pa shtetësi

Nëse e menaxhoni historikun e bisedave manualisht në anën e klientit (rast përdorimi pa shtetësi), duhet të përditësoni mënyrën e lidhjes sipas kthesave të mëparshme.

  • Trashëgimia : Zhvilluesit shpesh mblidhnin vargun e outputs nga përgjigjet dhe i dërgonin ato përsëri në fushën input në raundin tjetër.
  • Skemë e re : Tani duhet të mbledhësh vargun e steps nga përgjigjja dhe ta kalosh atë në fushën input së kërkesës tjetër, duke shtuar kthesën e re të përdoruesit si një hap user_input .

Konfigurimi i formatit të daljes: ndryshimet e response_format

API-ja e përditësuar konsolidon të gjitha kontrollet e formatit të daljes në një fushë të unifikuar, polimorfike response_format . Kjo e centralizon konfigurimin e daljes në nivelin më të lartë dhe e mban generation_config të fokusuar në sjelljen e modelit (si temperatura, top_p dhe të menduarit).

Ndryshime kryesore

  • API-ja heq response_mime_type . Tani ju specifikoni llojin MIME për çdo hyrje formati brenda response_format .
  • response_format tani është një objekt (ose varg) polimorfik. Çdo hyrje ka një dallues type ( text , audio , image ) dhe fusha specifike për tipin. Për të kërkuar modalitete të shumëfishta të daljes, kaloni një varg hyrjesh formati.
  • image_config kalon nga generation_config në response_format . Tani specifikoni cilësimet e daljes së imazhit si aspect_ratio dhe image_size në një hyrje response_format me "type": "image" .

Prodhimi i strukturuar (JSON)

Skema e re heq fushën response_mime_type . Në vend të kësaj, specifikoni llojin MIME dhe skemën JSON brenda një objekti response_format me "type": "text" .

Përpara (trashëgimi)

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);

PUSHTIM 

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

Pas (skema e re)

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);

PUSHTIM 

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

Konfigurimi i imazhit

Skema e re heq image_config nga generation_config . Tani mund të specifikoni cilësimet e daljes së imazhit në një hyrje response_format me "type": "image" .

Përpara (trashëgimi)

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'
        }
    },
});

PUSHTIM 

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

Pas (skema e re)

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'
    },
});

PUSHTIM 

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

Për të kërkuar modalitete të shumëfishta daljeje (për shembull, tekst dhe audio së bashku), kaloni një varg hyrjesh formati te response_format në vend të një objekti të vetëm.

Si të migroni në skemën e re

Përdoruesit e SDK-së

Përditësojeni në versionin më të fundit të SDK-së (Python ≥1.76.0, JavaScript ≥1.53.0). SDK-ja ju zgjedh automatikisht në skemën e re — nuk nevojiten ndryshime në kod përveç përditësimit të mënyrës se si i lexoni përgjigjet (shihni shembujt më sipër). Vini re se vetëm skema e re mbështetet në këto versione të SDK-së. Versionet më të vjetra të SDK-së (Python ≤1.73.1, JavaScript ≤1.50.1) do të vazhdojnë të funksionojnë derisa skema e trashëguar të hiqet më 6 qershor 2026 .

Përdoruesit e API-t REST

Shtoni kokën Api-Revision: 2026-05-20 në kërkesat tuaja për t'u regjistruar në skemën e re tani. Pas datës 20 maj , skema e re bëhet parazgjedhja për të gjitha kërkesat. Mund të zgjidhni të mos përdorni Api-Revision: 2026-05-06 përkohësisht deri më 6 qershor , kur API do ta heqë përgjithmonë skemën e trashëguar.

Kronologjia

Data Faza Përdoruesit e SDK-së Përdoruesit e API-t REST
6 maj Regjistrohu Versioni i ri kryesor i SDK-së është i disponueshëm (Python ≥2.0.0, JS ≥2.0.0). Përditësojeni për të marrë skemën e re automatikisht. Shto kokën Api-Revision: 2026-05-20 për t'u regjistruar. Vlera fillestare mbetet e trashëguar.
20 maj Kthesë e parazgjedhur Nuk nevojitet asnjë veprim nëse është përditësuar tashmë. SDK-të më të vjetra (Python 1.xx, JS 1.xx) ende funksionojnë, por kthejnë përgjigje të trashëguara. Skema e re është tani parazgjedhja. Dërgoni kokën Api-Revision: 2026-05-06 për të çregjistruar.
6 qershor Perëndim dielli Versionet 1.xx SDK për Python dhe JS do të kenë probleme për thirrjet e Interactions API. Skema e trashëguar u hoq për Interactions API. Titulli Api-Revision t u injorua.

Lista e Kontrollit të Migrimit

Skema e hapave ( steps )

  • Përditësoni kodin për të lexuar përmbajtjen e përgjigjes nga vargu i steps në vend të outputs . Shihni shembujt ..
  • Verifikoni që kodi juaj trajton të dy llojet e hapave user_input dhe model_output . Shihni shembujt ..
  • (Thirrja e Funksionit) Përditësoni kodin për të gjetur hapat function_call në vargun steps . Shihni shembuj ..
  • (Mjetet nga ana e serverit) Përditësoni kodin për të trajtuar hapat specifikë të mjetit (p.sh., google_search_call , google_search_result ). Shihni shembujt .
  • (Historiku pa shtetësi) Përditësoni menaxhimin e historikut për të kaluar vargun e steps në fushën input së kërkesës tjetër. Shihni detajet .
  • (Vetëm transmetim) Përditësoni klientin për të dëgjuar për lloje të reja ngjarjesh SSE ( interaction.created , step.delta , etj.). Shihni shembuj .

Konfigurimi i formatit të daljes ( response_format )

  • Zëvendëso response_mime_type me një fushë mime_type brenda response_format . Shih shembuj .
  • Mbështillni skemën tuaj ekzistuese JSON response_format brenda një objekti {"type": "text", "schema": ...} . Shihni shembujt .
  • (Gjenerimi i Imazhit) Zhvendos image_config nga generation_config në një hyrje {"type": "image", ...} në response_format . Shih shembujt .
  • (Multimodale) Konvertoni response_format nga një objekt i vetëm në një varg kur kërkoni modalitete të shumëfishta të daljes..