Gemini API reference

يوضّح مرجع واجهة برمجة التطبيقات هذا واجهات برمجة التطبيقات العادية والبث المباشر وفي الوقت الفعلي التي يمكنك استخدامها للتفاعل مع نماذج Gemini. يمكنك استخدام واجهات REST API في أي بيئة تتيح طلبات HTTP. راجِع دليل البدء السريع لمعرفة كيفية بدء استدعاء واجهة برمجة التطبيقات لأول مرة. إذا كنت تبحث عن مراجع لمكتباتنا وحِزم تطوير البرامج (SDK) الخاصة بلغة معيّنة، انتقِل إلى الرابط الخاص بهذه اللغة في قائمة التنقّل اليمنى ضمن مراجع حِزم تطوير البرامج (SDK).

نقاط النهاية الأساسية

تم تنظيم Gemini API حول نقاط النهاية الرئيسية التالية:

• إنشاء المحتوى العادي (generateContent): نقطة نهاية عادية لخدمة REST تعالج طلبك وتعرض الرد الكامل للنموذج في حزمة واحدة. هذا الخيار هو الأفضل للمهام غير التفاعلية التي يمكنك فيها انتظار النتيجة الكاملة.
• إنشاء المحتوى أثناء البث (streamGenerateContent): يستخدم هذا الخيار أحداثًا يتم إرسالها من الخادم (SSE) لإرسال أجزاء من الرد إليك أثناء إنشائها. يوفّر ذلك تجربة أسرع وأكثر تفاعلية للتطبيقات، مثل روبوتات الدردشة.
• Live API (BidiGenerateContent): هي واجهة برمجة تطبيقات مستندة إلى WebSocket مع الاحتفاظ بالحالة، ومصمّمة لحالات الاستخدام الحواري في الوقت الفعلي.
• وضع الدُفعات (batchGenerateContent): نقطة نهاية REST عادية لإرسال دُفعات من طلبات generateContent.
• التضمينات (embedContent): نقطة نهاية REST عادية تنشئ متّجه تضمين نصي من الإدخال Content.
• واجهات برمجة تطبيقات Gen Media: نقاط نهاية لإنشاء وسائط باستخدام نماذجنا المتخصصة، مثل Imagen لإنشاء الصور وVeo لإنشاء الفيديوهات تتضمّن Gemini أيضًا هذه الإمكانات التي يمكنك الوصول إليها باستخدام واجهة برمجة التطبيقات generateContent.
• واجهات برمجة التطبيقات الخاصة بالمنصة: نقاط نهاية الأدوات المساعدة التي تتيح إمكانات أساسية، مثل تحميل الملفات واحتساب الرموز المميزة.

المصادقة

يجب أن تتضمّن جميع الطلبات المُرسَلة إلى Gemini API عنوان x-goog-api-key مع مفتاح واجهة برمجة التطبيقات. يمكنك إنشاء واحد ببضع نقرات في Google AI Studio.

في ما يلي مثال على طلب يتضمّن مفتاح واجهة برمجة التطبيقات في العنوان:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

للحصول على تعليمات حول كيفية تمرير مفتاحك إلى واجهة برمجة التطبيقات باستخدام حِزم تطوير البرامج (SDK) من Gemini، راجِع دليل استخدام مفاتيح Gemini API.

إنشاء المحتوى

هذه هي نقطة النهاية المركزية لإرسال الطلبات إلى النموذج. هناك نقطتا نهاية لإنشاء المحتوى، ويكمن الاختلاف الرئيسي في طريقة تلقّي الردّ:

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

بنية نص الطلب

نص الطلب هو كائن JSON يكون متطابقًا في كل من الوضعين العادي والبث، ويتم إنشاؤه من بعض الكائنات الأساسية:

• عنصر Content: يمثّل دورة واحدة في محادثة.
• عنصر Part: هو جزء من البيانات ضمن Content دورة (مثل نص أو صورة).
• ‫inline_data (Blob): حاوية لبايتات الوسائط الأولية ونوع MIME الخاص بها.

على أعلى مستوى، يحتوي نص الطلب على الكائن contents، وهو عبارة عن قائمة بالكائنات Content، ويمثّل كل منها منعطفًا في المحادثة. في معظم الحالات، سيكون لديك عنصر Content واحد لإنشاء نص أساسي، ولكن إذا أردت الاحتفاظ بسجلّ المحادثات، يمكنك استخدام عناصر Content متعددة.

يوضّح ما يلي نص طلب generateContent نموذجيًا:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

بنية نص الاستجابة

نص الرد متشابه في كل من الوضعين العادي والبث المباشر، باستثناء ما يلي:

• الوضع العادي: يحتوي نص الاستجابة على مثال GenerateContentResponse.
• وضع العرض التدريجي: يحتوي نص الاستجابة على سلسلة من أمثلة GenerateContentResponse.

بشكل عام، يحتوي نص الاستجابة على كائن candidates، وهو عبارة عن قائمة بكائنات Candidate. يحتوي العنصر Candidate على العنصر Content الذي يتضمّن الردّ الذي تم إنشاؤه من النموذج.

أمثلة على الطلبات

توضّح الأمثلة التالية كيفية تجميع هذه المكوّنات لأنواع مختلفة من الطلبات.

طلب نصي فقط

يتألف الطلب النصي البسيط من مصفوفة contents تحتوي على عنصر Content واحد. تحتوي مصفوفة parts الخاصة بهذا العنصر على عنصر Part واحد يتضمّن الحقل text.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

طلب متعدّد الوسائط (نص وصورة)

لتوفير نص وصورة في الطلب، يجب أن تحتوي مصفوفة parts على كائنَي Part، أحدهما للنص والآخر للصورة inline_data.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

المحادثات المتعدّدة الجولات (المحادثة)

لإنشاء محادثة تتضمّن عدة أدوار، عليك تحديد مصفوفة contents التي تتضمّن عدة عناصر Content. ستستخدم واجهة برمجة التطبيقات سجلّ المحادثات الكامل هذا كسياق للرد التالي. يجب أن يتناوب role لكل عنصر Content بين user وmodel.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

الخلاصات الرئيسية

• Content هو الظرف: وهو الحاوية ذات المستوى الأعلى الخاصة بدورة الرسالة، سواء كانت من المستخدم أو النموذج.
• تتيح Part استخدام وسائط متعددة: استخدِم عدة عناصر Part ضمن عنصر Content واحد لدمج أنواع مختلفة من البيانات (نص، صورة، معرّف الموارد المنتظم للفيديو، وما إلى ذلك).
• اختَر طريقة البيانات:
  • بالنسبة إلى الوسائط الصغيرة المضمّنة مباشرةً (مثل معظم الصور)، استخدِم Part مع inline_data.
  • بالنسبة إلى الملفات الأكبر حجمًا أو الملفات التي تريد إعادة استخدامها في طلبات متعددة، استخدِم File API لتحميل الملف والإشارة إليه باستخدام جزء file_data.
• إدارة سجلّ المحادثات: بالنسبة إلى تطبيقات المحادثة التي تستخدم واجهة REST API، أنشئ مصفوفة contents عن طريق إضافة عناصر Content لكل دورة، بالتناوب بين الأدوار "user" و"model". إذا كنت تستخدم حزمة SDK، يُرجى الرجوع إلى مستندات حزمة SDK لمعرفة الطريقة المقترَحة لإدارة سجلّ المحادثات.

أمثلة على الردود

توضّح الأمثلة التالية كيفية تجميع هذه المكوّنات لأنواع مختلفة من الطلبات.

ردّ نصي فقط

تتألف الاستجابة النصية التلقائية من مصفوفة candidates تحتوي على كائن واحد أو أكثر من كائنات content التي تتضمّن استجابة النموذج.

في ما يلي مثال على رد عادي:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

في ما يلي سلسلة من الردود المتدفقة. يحتوي كل ردّ على responseId يربط الردّ الكامل ببعضه:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets API

توفّر Live API واجهة برمجة تطبيقات مستندة إلى WebSocket مع الاحتفاظ بالحالة، وذلك للبث الثنائي الاتجاه بهدف إتاحة حالات استخدام البث في الوقت الفعلي. يمكنك مراجعة دليل Live API ومرجع Live API للحصول على مزيد من التفاصيل.

النماذج المتخصّصة

بالإضافة إلى مجموعة نماذج Gemini، يوفّر Gemini API نقاط نهاية لنماذج متخصّصة، مثل Imagen وLyria ونماذج التضمين. يمكنك الاطّلاع على هذه الأدلة ضمن قسم "نماذج".

واجهات برمجة التطبيقات الخاصة بالمنصة

تتيح نقاط النهاية المتبقية إمكانات إضافية يمكن استخدامها مع نقاط النهاية الرئيسية الموضّحة حتى الآن. يمكنك الاطّلاع على الموضوعَين وضع الدُفعات و واجهة برمجة التطبيقات للملفات في قسم "الأدلة" لمعرفة المزيد.

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

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

• البدء السريع في Gemini API
• دليل نماذج Gemini

يمكنك أيضًا الاطّلاع على أدلة الإمكانات التي تقدّم ميزات مختلفة في Gemini API وتوفّر أمثلة على الرموز البرمجية:

• إنشاء النصوص
• تخزين السياق مؤقتًا
• عمليات التضمين