دليل البدء السريع لاستخدام Gemini API

يوضّح لك هذا الدليل السريع كيفية تثبيت مكتباتنا وإجراء أول طلب بيانات من واجهة برمجة التطبيقات إلى Gemini API باستخدام Interactions API.

قبل البدء

لاستخدام Gemini API، يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات للمصادقة على طلباتك وفرض حدود الأمان وتتبُّع الاستخدام في حسابك.

يمكنك إنشاء مفتاح مجانًا على AI Studio للبدء:

إنشاء مفتاح Gemini API

تثبيت حزمة Google GenAI SDK

pip install -q -U google-genai

npm install @google/genai

إجراء أول طلب

هناك طريقتان لإرسال طلب إلى Gemini API:

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

يستخدم هذا المثال Interactions API لإرسال طلب إلى Gemini API باستخدام نموذج Gemini 3 Flash.

إذا ضبطت مفتاح واجهة برمجة التطبيقات كمتغيّر بيئة GEMINI_API_KEY، سيختاره العميل تلقائيًا عند استخدام مكتبات Gemini API. وإلا، عليك تمرير مفتاح واجهة برمجة التطبيقات كـ حجة عند تهيئة العميل.

يُرجى العِلم أنّ جميع نماذج الرموز البرمجية في مستندات Gemini API تفترض أنّك ضبطت متغيّر البيئة GEMINI_API_KEY.

# This will only work for SDK newer than 2.0.0
from google import genai

# The client gets the API key from the environment variable `GEMINI_API_KEY`.
client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview", 
    input="Explain how AI works in a few words"
)

# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

// The client gets the API key from the environment variable `GEMINI_API_KEY`.
const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain how AI works in a few words",
  });

  const modelStep = interaction.steps.find(s => s.type === 'model_output');
  if (modelStep) {
    for (const contentBlock of modelStep.content) {
      if (contentBlock.type === 'text') console.log(contentBlock.text);
    }
  }
}

main();

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain how AI works in a few words"
  }'

الوضع بدون حالة

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

للحصول على التفاصيل والأمثلة الكاملة بدون حالة المتعددة الأدوار، يُرجى الاطّلاع على دليل إنشاء النصوص.

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

بعد إجراء أول طلب بيانات من واجهة برمجة التطبيقات، قد يهمّك استكشاف الأدلة التالية التي تعرض Gemini أثناء العمل:

• إنشاء النصوص
• إنشاء الصور
• فهم الصور
• التفكير
• استدعاء الدوال
• سياق طويل
• المتجهات الدلالية