واجهة برمجة التطبيقات Interactions API

‫Interactions API هي أفضل طريقة للتصميم باستخدام نماذج Gemini والوكلاء. اعتبارًا من يونيو 2026، ستصبح واجهة برمجة التطبيقات متاحة للجميع وننصح باستخدامها في جميع المشاريع الجديدة. على الرغم من أنّها تُعدّ الآن واجهة برمجة تطبيقات قديمة، لا تزال واجهة برمجة التطبيقات الأصلية generateContent متوافقة بشكلٍ كامل.

أهمية استخدام Interactions API

• واجهة عالمية لجميع التطبيقات: تم تصميمها لتكون الواجهة العادية لكل حالات الاستخدام، بما في ذلك إنشاء النصوص في محادثة واحدة، والفهم المتعدّد الوسائط، والنتائج المنظَّمة، وتنسيق الأدوات، وسير عمل الوكلاء.
• واجهة برمجة تطبيقات واحدة للنماذج والوكلاء: نقطة نهاية ونمط موحّدان لـ استدعاء نماذج Gemini العادية والوكلاء المتخصّصين مباشرةً (مثل Deep Research والوكلاء المخصّصين المُدارين).
• إمكانات جديدة جاهزة للاستخدام: ميزات مثل حالة المحادثة الاختيارية من جهة الخادم باستخدام previous_interaction_id، وخطوات التنفيذ القابلة للمراقبة لأغراض تصحيح الأخطاء وعرض واجهة المستخدم، والتنفيذ في الخلفية للمهام الطويلة الأمد باستخدام 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
• الاستنتاج المرن
• الاستنتاج حسب الأولوية

طريقة عمل 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 وما إلى ذلك)

يعني ذلك أنّه عليك إعادة تحديد هذه المَعلمات في كل تفاعل جديد إذا كنت تريد تطبيقها. تُعدّ إدارة الحالة من جهة الخادم اختيارية، ويمكنك أيضًا العمل في وضع "عدم حفظ السياق" من خلال إرسال سجلّ المحادثة الكامل في كل طلب.

تخزين البيانات والاحتفاظ بها

تخزّن واجهة برمجة التطبيقات تلقائيًا جميع عناصر `Interaction` (store=true) لتسهيل استخدام ميزات إدارة الحالة من جهة الخادم (باستخدام previous_interaction_id)، التنفيذ في الخلفية (باستخدام background=true) ولأغراض إمكانية تتبّع البيانات.

• المستوى المدفوع: يحتفظ النظام بالتفاعلات لمدة 55 يومًا.
• المستوى المجاني: يحتفظ النظام بالتفاعلات لمدة يوم واحد.

إذا كنت لا تريد ذلك، يمكنك ضبط store=false في طلبك. يختلف عنصر التحكّم هذا عن إدارة الحالة، ويمكنك إيقاف التخزين لأي تفاعل. يُرجى العِلم أنّ store=false غير متوافق مع التنفيذ في الخلفية ويمنع استخدام previous_interaction_id في المحادثات اللاحقة.

بالنسبة إلى مشاريع المستوى المدفوع، يمكنك ضبط فترة الاحتفاظ في AI Studio لوضع علامة تلقائيًا على السجلّات لحذفها من مساحة تخزين المشروع بعد 7 أو 14 أو 28 أو 55 يومًا. قد يؤثر الاحتفاظ لفترة أقصر في استرداد المحادثات السابقة.

يمكنك حذف التفاعلات المخزَّنة في أي وقت باستخدام الـ delete طريقة آليًا، ما يتطلّب رقم تعريف التفاعل. يمكنك أيضًا عرض سجلّات التفاعلات المخزَّنة وإدارتها في AI Studio، بما في ذلك حذفها من مساحة تخزين المشروع.

بعد انتهاء فترة الاحتفاظ، سيتم حذف بياناتك تلقائيًا.

تتم معالجة عناصر التفاعلات وفقًا لـ الأحكام.

عرض التفاعلات في AI Studio

تخزّن واجهة برمجة التطبيقات طلبات Interactions API التي تم تنفيذها باستخدام store=true للمشاريع على المستوى المدفوع. يمكنك عرضها مباشرةً من الـ صفحة "السجلّات" في Google AI Studio. لمزيد من المعلومات، يُرجى الاطّلاع على دليل السجلّات .

أفضل الممارسات

• معدّل نتائج ذاكرة التخزين المؤقت: يتم دعم التخزين المؤقت الضمني في الوضعَين المستند إلى الحالة و وضع "عدم حفظ السياق" (راجِع دليل البدء السريع). يسمح استخدام previous_interaction_id (المستند إلى الحالة) لمتابعة المحادثات للنظام بالاستفادة من التخزين المؤقت الضمني لسجلّ المحادثة بسهولة أكبر، ما يحسّن الأداء ويقلّل التكاليف.
• الجمع بين التفاعلات: يمكنك الجمع بين تفاعلات الوكيل و النموذج في محادثة واحدة. على سبيل المثال، يمكنك استخدام وكيل متخصّص، مثل وكيل Deep Research، لجمع البيانات الأولية، ثم استخدام نموذج Gemini عادي للمهام اللاحقة، مثل التلخيص أو إعادة التنسيق، وربط هذه الخطوات باستخدام previous_interaction_id.

النماذج والوكلاء المتوافقون

حزم SDK

يمكنك استخدام أحدث إصدار من حزم Google GenAI SDK للوصول إلى Interactions API.

• في Python، هذه هي حزمة google-genai من الإصدار 2.3.0 والإصدارات الأحدث.
• في JavaScript، هذه هي حزمة @google/genai من الإصدار 2.3.0 والإصدارات الأحدث.
• في Go، هذه هي حزمة google.golang.org/genai.
• في Java، هذه هي حزمة com.google.genai:google-genai.

يمكنك الاطّلاع على مزيد من المعلومات حول كيفية تثبيت حزم SDK في صفحة " المكتبات".

القيود

• خادم MCP عن بُعد: لا يتوافق Gemini 3 مع خادم MCP عن بُعد، وسيتم توفير هذه الميزة قريبًا.
• توافُق النموذج مع المحادثات المتعدّدة: عند الجمع بين نماذج مختلفة في محادثة (سواء كانت مستندة إلى الحالة أو غير مستندة إلى الحالة)، يجب أن تتوافق النماذج اللاحقة مع أساليب الإخراج الخاصة بالنماذج السابقة كمدخلات. على سبيل المثال، إذا أنشأت صورة باستخدام gemini-3.1-flash-image، لا يمكنك متابعة هذه المحادثة باستخدام نموذج لا يقبل مدخلات الصور (مثل نموذج نصي فقط أو نموذج لإنشاء الموسيقى مثل Lyria).

تتوافق واجهة برمجة التطبيقات generateContent مع الميزات التالية، ولكن لا تتوفّر بعد في Interactions API:

• ‫**Batch API**
• ‫**استدعاء الدالة التلقائي (Python)**
• التخزين المؤقت الصريح: يُرجى العِلم أنّ التخزين المؤقت الضمني من جهة الخادم متاح في Interactions API عبر previous_interaction_id.

الملاحظات

ملاحظاتك ضرورية لتطوير Interactions API. يمكنك مشاركة أفكارك أو الإبلاغ عن الأخطاء أو طلب ميزات في منتدى مطوّري Google AI.

الخطوات التالية

• جرِّب دفتر ملاحظات البدء السريع في Interactions API.
• مزيد من المعلومات حول وكيل Deep Research في Gemini.