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

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

ما هي مزايا استخدام Interactions API؟

• واجهة شاملة لجميع التطبيقات: تم تصميمها لتكون الواجهة العادية لكل حالة استخدام، بما في ذلك إنشاء النصوص من طلب واحد، وفهم المحتوى المتعدّد الوسائط، والمخرجات المنظَّمة، وتنظيم الأدوات، وسير العمل المستند إلى الوكلاء.
• واجهة برمجة تطبيقات واحدة للنماذج والوكلاء: نقطة نهاية ونمط موحّدان لاستدعاء نماذج Gemini العادية والوكلاء المتخصّصين مباشرةً (مثل Deep Research والوكلاء المُدارين المخصّصين).
• إمكانات جديدة جاهزة للاستخدام: ميزات مثل حالة المحادثة الاختيارية من جهة الخادم باستخدام previous_interaction_id، وخطوات التنفيذ القابلة للتتبّع لتصحيح الأخطاء وعرض واجهة المستخدم، والتنفيذ في الخلفية للمهام التي تستغرق وقتًا طويلاً باستخدام background=true.
• انخفاض التكلفة مع ارتفاع معدّلات نتيجة ذاكرة التخزين المؤقت: عند استخدام المحادثات المترابطة، تتيح إدارة الحالة الاختيارية من جهة الخادم التخزين المؤقت للسياق بشكل أكثر كفاءة في جميع الجولات، ما يقلّل من تكاليف الرموز المميّزة.
• إطلاق الميزات الجديدة: من الآن فصاعدًا، سيتم إطلاق جميع النماذج الجديدة والإمكانات المتعددة الوسائط والأدوات والميزات المستندة إلى الذكاء الاصطناعي الوكيل من خلال Interactions API.

تخزّن واجهة Interactions API الطلبات تلقائيًا حتى تتمكّن من الاستفادة من ميزات إدارة الحالة من جهة الخادم باستخدام previous_interaction_id. يمكنك تفعيل السلوك غير المرتبط بحالة من خلال ضبط store=false. يمكنك الاطّلاع على قسم الاحتفاظ بالبيانات لمعرفة التفاصيل.

البدء

• إعداد وكيل الترميز: اربط وكيل الترميز ببروتوكول MCP الخاص بـ "مستندات Gemini" وثبِّت مهارة 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 (مع الاحتفاظ بالحالة) لمواصلة المحادثات للنظام الاستفادة بسهولة أكبر من التخزين المؤقت الضمني لسجلّ المحادثات، ما يؤدي إلى تحسين الأداء وخفض التكاليف.
• الجمع بين التفاعلات: يمكنك الجمع بين تفاعلات الوكيل والنموذج ضمن محادثة واحدة. على سبيل المثال، يمكنك استخدام وكيل متخصص، مثل وكيل "البحث المعمّق"، لجمع البيانات الأولية، ثم استخدام نموذج 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 استخدام إعدادات الأمان المخصّصة.

الملاحظات

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

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

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