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 ونماذج التضمين. يمكنك الاطّلاع على هذه الأدلة ضمن قسم "نماذج".

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

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

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

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

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

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

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