Gemini API reference

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

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

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

• إنشاء المحتوى العادي (generateContent): نقطة نهاية عادية لطلبات REST تعالج طلبكم وتعرض الردّ الكامل للنموذج في حزمة واحدة. هذه النقطة هي الأفضل للمهام غير التفاعلية التي يمكنكم فيها انتظار النتيجة الكاملة.
• إنشاء المحتوى المتدفّق (streamGenerateContent): تستخدم هذه النقطة أحداثًا مرسَلة من الخادم (SSE) لإرسال أجزاء من الردّ إليكم أثناء إنشائها. ويوفّر ذلك تجربة أسرع وأكثر تفاعلاً للتطبيقات، مثل روبوتات الدردشة.
• واجهة برمجة التطبيقات المباشرة (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"
          }
        ]
      }
    ]
  }'

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

واجهة برمجة التطبيقات المباشرة (BidiGenerateContent) WebSockets API

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

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

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

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

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

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

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

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

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

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