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.
• واجهات برمجة تطبيقات الوسائط من إنشاء الذكاء الاصطناعي التوليدي: نقاط نهاية لإنشاء وسائط باستخدام نماذجنا المتخصصة، مثل 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 وتوفّر أمثلة على الرموز البرمجية:

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