Interactions API

Gemini মডেল ও এজেন্টের সাথে কাজ করার সবচেয়ে ভালো উপায় হল Interactions API. জুন ২০২৬ পর্যন্ত, এটি সাধারণভাবে উপলভ্য এবং সব নতুন প্রোজেক্টের জন্য সাজেস্ট করা হয়। এটি এখন লেগ্যাসি হিসেবে বিবেচিত হলেও, আসল generateContent API সম্পূর্ণভাবে কাজ করে।

Interactions API কেন ব্যবহার করব?

• সব অ্যাপ্লিকেশনের জন্য ইউনিভার্সাল ইন্টারফেস: সিঙ্গেল-টার্ন টেক্সট জেনারেশন, মাল্টিমোডাল বোঝা, স্ট্রাকচার্ড আউটপুট, টুল অর্কেস্ট্রেশন ও এজেন্টিক ওয়ার্কফ্লো সহ প্রতিটি ব্যবহারের ক্ষেত্রে স্ট্যান্ডার্ড ইন্টারফেস হিসেবে ডিজাইন করা হয়েছে।
• মডেল ও এজেন্টের জন্য একটি API: স্ট্যান্ডার্ড Gemini মডেলের পাশাপাশি সরাসরি বিশেষ এজেন্টদের (যেমন Deep Research ও কাস্টম ম্যানেজড এজেন্ট) কল করার জন্য একটি ইউনিফায়েড এন্ডপয়েন্ট ও প্যাটার্ন।
• আলাদা করে কিছু না করেই নতুন নতুন সুবিধা: ঐচ্ছিক সার্ভার-সাইড কনভার্সেশন স্টেট ব্যবহার করে previous_interaction_id, ডিবাগিং ও UI রেন্ডারিংয়ের জন্য পর্যবেক্ষণযোগ্য এক্সিকিউশন স্টেপ এবং background=true ব্যবহার করে দীর্ঘমেয়াদী টাস্কের জন্য ব্যাকগ্রাউন্ড এক্সিকিউশন-এর মতো ফিচার।
• বেশি ক্যাশে হিট রেট সহ কম খরচ: মাল্টি-টার্ন কনভার্সেশন ব্যবহার করার সময়, ঐচ্ছিক সার্ভার-সাইড স্টেট ম্যানেজমেন্ট, টার্ন জুড়ে আরও বেশি কার্যকর কন্টেক্সট ক্যাশিং চালু করে, যার ফলে টোকেন খরচ কমে যায়।
• নতুন ফিচার কোথায় লঞ্চ করা হয়: এখন থেকে, সব নতুন মডেল, মাল্টিমোডাল ক্ষমতা, টুল ও এজেন্টিক ফিচার Interactions API-তে লঞ্চ করা হবে।

ডিফল্ট হিসেবে, Interactions API অনুরোধ সেভ করে রাখে যাতে আপনি previous_interaction_id ব্যবহার করে সার্ভার-সাইড স্টেট ম্যানেজমেন্ট ফিচার কাজে লাগাতে পারেন। আপনি store=false সেট করে স্টেটলেস আচরণে অপ্ট-ইন করতে পারবেন। আরও বিবরণের জন্য ডেটা কতদিন রাখা হয় বিভাগ দেখুন।

শুরু করুন

• আপনার কোডিং এজেন্ট সেট-আপ করুন: Gemini Docs MCP-এর সাথে কানেক্ট করুন এবং লেটেস্ট ডেভেলপার ডকুমেন্ট ও পেশাদার পদ্ধতি সরাসরি অ্যাক্সেস করার জন্য আপনার অ্যাসিস্ট্যান্টকে gemini-api-dev স্কিল দিন। বিস্তারিত ধাপের জন্য, আপনার কোডিং এজেন্ট গাইড সেট-আপ করুন দেখুন
• generateContent থেকে মাইগ্রেট করা: আপনার আগে থেকে কোনও ইন্টিগ্রেশন থাকলে, Interactions API-তে ট্রানজিশন করতে মাইগ্রেশন গাইড অনুসরণ করুন।
• শুরু করা যাক: Interactions API শুরু করা যাক গাইড-এ উল্লেখ করা ধাপগুলি অনুসরণ করুন।

ফিচার গাইড

এইসব নির্দেশিকার মাধ্যমে Interactions API-এর নির্দিষ্ট ক্ষমতা এক্সপ্লোর করুন। generateContent ও Interactions API-এর মধ্যে পরিবর্তন করতে, আপনি এইসব পৃষ্ঠায় টগল ব্যবহার করতে পারবেন:

• টেক্সট জেনারেশন
• ইমেজ জেনারেশন
• ছবি বোঝা
• অডিও বোঝা
• ভিডিও বোঝা
• ডকুমেন্ট প্রসেসিং
• ফাংশন কলিং
• স্ট্রাকচার্ড আউটপুট
• Deep Research এজেন্ট
• Flex inference
• অগ্রাধিকার সংক্রান্ত অনুমান

Interactions API কীভাবে কাজ করে

Interactions API একটি মূল রিসোর্সকে কেন্দ্র করে তৈরি হয়েছে: Interaction. Interaction কথোপকথন বা টাস্কের একটি সম্পূর্ণ পালাকে বোঝায়। এটি সেশন রেকর্ড হিসেবে কাজ করে, যার মধ্যে এক্সিকিউশন ধাপ-এর কালানুক্রমিক ক্রম হিসেবে ইন্টার‍্যাকশনের সম্পূর্ণ ইতিহাস থাকে। এইসব ধাপের মধ্যে মডেলের চিন্তাভাবনা, সার্ভার-সাইড বা ক্লায়েন্ট-সাইড টুল কল ও ফলাফল (যেমন function_call ও function_result) এবং চূড়ান্ত model_output অন্তর্ভুক্ত। স্টোর করা রিসোর্সে (interactions.get-এর মাধ্যমে পাওয়া) সম্পূর্ণ কনটেক্সটের জন্য user_input ধাপও অন্তর্ভুক্ত থাকে, যদিও interactions.create উত্তরে শুধুমাত্র মডেল-জেনারেটেড ধাপ দেখানো হয়।

আপনি interactions.create-এ কল করলে, আপনি নতুন Interaction রিসোর্স তৈরি করছেন:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'

সার্ভার-সাইড স্টেট ম্যানেজমেন্ট

কথোপকথন চালিয়ে যেতে, পরবর্তী কলে সম্পূর্ণ হওয়া ইন্টার‍্যাকশনের id-এর সাথে previous_interaction_id প্যারামিটার ব্যবহার করতে পারেন। কথোপকথনের ইতিহাস ফিরিয়ে আনতে সার্ভার এই আইডি ব্যবহার করে। এর ফলে আপনাকে সম্পূর্ণ চ্যাট ইতিহাস আবার পাঠাতে হয় না:

from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}

# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID"
  }'

previous_interaction_id প্যারামিটার শুধুমাত্র কথোপকথনের ইতিহাস (ইনপুট ও আউটপুট) previous_interaction_id ব্যবহার করে সেভ করে। অন্যান্য প্যারামিটার হল ইন্টার‍্যাকশন-স্কোপড এবং আপনি বর্তমানে যে নির্দিষ্ট ইন্টার‍্যাকশন তৈরি করছেন শুধুমাত্র সেটির ক্ষেত্রেই প্রযোজ্য:

• tools
• system_instruction
• generation_config (thinking_level, temperature ইত্যাদি সহ)

এর অর্থ হল, আপনি যদি চান যে এগুলি প্রয়োগ করা হোক, তাহলে প্রতিটি নতুন ইন্টার‍্যাকশনে আপনাকে অবশ্যই এইসব প্যারামিটার আবার উল্লেখ করতে হবে। এই সার্ভার-সাইড স্টেট ম্যানেজমেন্ট ঐচ্ছিক; আপনি প্রতিটি অনুরোধে সম্পূর্ণ কথোপকথনের ইতিহাস পাঠিয়েও স্টেটলেস মোডে কাজ করতে পারেন।

ডেটা স্টোরেজ ও ডেটা কতদিন রাখা হবে

ডিফল্ট হিসেবে, API সব ইন্টার‍্যাকশন অবজেক্ট (store=true) স্টোর করে যাতে সার্ভার-সাইড স্টেট ম্যানেজমেন্ট ফিচারের (previous_interaction_id সহ), ব্যাকগ্রাউন্ড এক্সিকিউশন (background=true ব্যবহার করে) এবং অবজার্ভেবিলিটি সংক্রান্ত উদ্দেশ্য পূরণ করা যায়।

• পেড টিয়ার: সিস্টেম ৫৫ দিন ধরে ইন্টার‍্যাকশন সেভ করে রাখে।
• ফ্রি টিয়ার: সিস্টেম ১ দিন ইন্টার‍্যাকশন সেভ করে রাখে।

আপনি এটি না চাইলে, আপনার অনুরোধে store=false সেট করতে পারেন। এই কন্ট্রোল স্টেট ম্যানেজমেন্ট থেকে আলাদা; আপনি যেকোনও ইন্টার‍্যাকশনের জন্য স্টোরেজ থেকে বেরিয়ে আসতে পারবেন। তবে, মনে রাখবেন যে store=false ব্যাকগ্রাউন্ড এক্সিকিউশন-এর সাথে মানানসই নয় এবং এর ফলে পরবর্তী টার্নে previous_interaction_id ব্যবহার করা যায় না।

পেইড টিয়ার প্রোজেক্টের জন্য, আপনি AI Studio-তে রিটেনশন উইন্ডো কনফিগার করতে পারবেন, যাতে ৭, ১৪, ২৮ বা ৫৫ দিন পরে প্রোজেক্ট স্টোরেজ থেকে লগ অটোমেটিক মুছে ফেলা যায়। কম সময় ধরে ডেটা সেভ করে রাখলে পুরনো কথোপকথন ফিরিয়ে আনার ক্ষেত্রে সমস্যা হতে পারে।

আপনি যেকোনও সময় delete পদ্ধতি প্রোগ্রাম্যাটিক উপায়ে ব্যবহার করে স্টোর করা ইন্টার‍্যাকশন মুছে দিতে পারবেন, এর জন্য ইন্টার‍্যাকশন আইডি প্রয়োজন। এছাড়াও, আপনি AI Studio-তে প্রজেক্ট স্টোরেজ থেকে মুছে দেওয়া সহ সেভ করা ইন্টার‍্যাকশন লগ দেখতে ও ম্যানেজ করতে পারবেন।

ডেটা ধরে রাখার সময়সীমা শেষ হয়ে গেলে, আপনার ডেটা অটোমেটিক মুছে দেওয়া হবে।

ইন্টার‍্যাকশন অবজেক্ট শর্তাবলী অনুযায়ী প্রসেস করা হয়।

AI Studio-তে ইন্টার‍্যাকশন দেখা

API, পেড টিয়ারে store=true-এর মাধ্যমে প্রজেক্টের জন্য এক্সিকিউট করা ইন্ট্যার‍্যাকশন API অনুরোধ সেভ করে। আপনি সরাসরি Google AI Studio-র লগ পৃষ্ঠা থেকে সেগুলি দেখতে পারবেন। আরও জানতে লগ গাইড দেখুন।

পেশাদার পদ্ধতি

• ক্যাশে হিট রেট: ইমপ্লিসিট ক্যাশিং স্টেটফুল ও স্টেটলেস, দুটি মোডেই কাজ করে (দেখুন দ্রুত শুরু করা)। কথোপকথন চালিয়ে যেতে previous_interaction_id (স্টেটফুল) ব্যবহার করলে, সিস্টেম কথোপকথনের ইতিহাসের জন্য আরও সহজে ইমপ্লিসিট ক্যাশিং ব্যবহার করতে পারে, যা পারফর্ম্যান্স উন্নত করে এবং খরচ কমায়।
• ইন্টার‍্যাকশন মেশানো: কথোপকথনের মধ্যে এজেন্ট ও মডেল ইন্টার‍্যাকশন মেশানোর সুবিধা আপনার কাছে আছে। যেমন, প্রাথমিক ডেটা সংগ্রহের জন্য আপনি Deep Research এজেন্টের মতো বিশেষ এজেন্ট ব্যবহার করতে পারেন এবং তারপরে ফলো-আপ টাস্কের জন্য স্ট্যান্ডার্ড Gemini মডেল ব্যবহার করতে পারেন, যেমন সারসংক্ষেপ তৈরি করা বা রিফর্ম্যাট করা, এই ধাপগুলিকে previous_interaction_id-এর সাথে লিঙ্ক করা।

কাজ করে এমন মডেল ও এজেন্ট

SDK

আপনি ইন্ট্যার‍্যাকশন API অ্যাক্সেস করতে Google GenAI SDK-এর লেটেস্ট ভার্সন ব্যবহার করতে পারবেন।

• Python-এ, এটি 2.3.0 ভার্সন থেকে google-genai প্যাকেজ।
• JavaScript-এ, এটি @google/genai ভার্সন 2.3.0 থেকে শুরু করে।
• On Go-তে এটি google.golang.org/genai প্যাকেজ।
• Java-তে এটি com.google.genai:google-genai প্যাকেজ।

আপনি কীভাবে SDK ইনস্টল করবেন সেই সম্পর্কে লাইব্রেরি পৃষ্ঠা থেকে আরও জানতে পারবেন।

সীমাবদ্ধতা

• রিমোট MCP: Gemini 3 রিমোট MCP-তে কাজ করে না, এটি শীঘ্রই উপলভ্য হবে।
• মাল্টি-টার্ন মডেলের উপযুক্ততা: কোনও কথোপকথনে (স্টেটফুল বা স্টেটলেস) বিভিন্ন মডেল মিশিয়ে দিলে, পরবর্তী মডেলগুলিকে অবশ্যই আগের মডেলের আউটপুট মোডালিটি ইনপুট হিসেবে গ্রহণ করতে হবে। যেমন, আপনি যদি gemini-3.1-flash-image ব্যবহার করে কোনও ছবি জেনারেট করেন, তাহলে আপনি সেই কথোপকথনটি এমন কোনও মডেলের সাথে চালিয়ে যেতে পারবেন না যা ছবি ইনপুট নেয় না (যেমন, একটি শুধুমাত্র টেক্সট-ভিত্তিক মডেল বা Lyria-র মতো মিউজিক-জেনারেটিং মডেল)।

নিচে উল্লেখ করা ফিচারগুলি generateContent API-তে কাজ করে, কিন্তু Interactions API-তে এখনও উপলভ্য নেই:

• Batch API
• অটোমেটিক ফাংশন কলিং (Python)
• এক্সপ্লিসিট ক্যাশিং: মনে রাখবেন, Interactions API-এর মাধ্যমে previous_interaction_id সার্ভার-সাইড ইমপ্লিসিট ক্যাশিং উপলভ্য।
• নিরাপত্তা সেটিংস: ইন্ট্যার‍্যাকশন API-তে কাস্টম নিরাপত্তা সেটিংস কাজ করে না।

মতামত

Interactions API-এর ডেভেলপমেন্টের জন্য আপনার মতামত খুবই গুরুত্বপূর্ণ। আমাদের Google AI ডেভেলপার কমিউনিটি ফোরামে আপনার মতামত শেয়ার করুন, বাগ সম্পর্কে অভিযোগ জানান অথবা ফিচারের অনুরোধ করুন।

এর পরে কী করতে হবে

• Interactions API ক্যুইকস্টার্ট নোটবুক ব্যবহার করে দেখুন।
• Gemini Deep Research এজেন্ট সম্পর্কে আরও জানুন।