Gemini API reference

במסמך הזה מפורטות הפניות ל-API הרגיל, ל-API של סטרימינג ול-API בזמן אמת, שבהם אפשר להשתמש כדי ליצור אינטראקציה עם מודלים של Gemini. אפשר להשתמש בממשקי REST API בכל סביבה שתומכת בבקשות HTTP. במדריך למתחילים מוסבר איך להתחיל להשתמש ב-API וליצור את הקריאה הראשונה ל-API. אם אתם מחפשים את ההפניות לספריות ולערכות ה-SDK הספציפיות לשפה שלנו, אתם יכולים לעבור לקישור של השפה הרלוונטית בניווט הימני בקטע הפניות ל-SDK.

נקודות קצה ראשיות

‫Gemini API מאורגן סביב נקודות הקצה העיקריות הבאות:

  • יצירת תוכן רגילה (generateContent): נקודת קצה רגילה של REST שמבצעת את הבקשה ומחזירה את התגובה המלאה של המודל בחבילה אחת. האפשרות הזו מתאימה למשימות לא אינטראקטיביות שבהן אפשר לחכות לתוצאה המלאה.
  • יצירת תוכן בסטרימינג (streamGenerateContent): משתמשת באירועים שנשלחים מהשרת (SSE) כדי לשלוח לכם נתחים מהתשובה בזמן שהם נוצרים. כך אפשר לספק חוויה מהירה ואינטראקטיבית יותר לאפליקציות כמו צ'אטבוטים.
  • ‫Live API ‏ (BidiGenerateContent): ממשק API מבוסס WebSocket עם שמירת מצב לסטרימינג דו-כיווני, שנועד לתרחישי שימוש שיחות בזמן אמת.
  • מצב אצווה (batchGenerateContent): נקודת קצה רגילה של REST לשליחת אצוות של בקשות generateContent.
  • הטמעות (embedContent): נקודת קצה רגילה של REST שיוצרת וקטור הטמעה של טקסט מהקלט Content.
  • ‫Gen Media APIs: נקודות קצה ליצירת מדיה באמצעות המודלים המיוחדים שלנו, כמו Imagen ליצירת תמונות ו-Veo ליצירת סרטונים. היכולות האלה מובנות גם ב-Gemini, ואפשר לגשת אליהן באמצעות generateContent API.
  • ‫Platform APIs: נקודות קצה (endpoints) של כלי עזר שתומכות ביכולות ליבה כמו העלאת קבצים וספירת טוקנים.

אימות

כל הבקשות ל-Gemini API חייבות לכלול כותרת x-goog-api-key עם מפתח ה-API שלכם. אפשר ליצור סרטון חדש בכמה קליקים ב-Google AI Studio.

בדוגמה הבאה מוצגת בקשה עם מפתח ה-API שכלול בכותרת:

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"
          }
        ]
      }
    ]
  }'

הוראות להעברת המפתח ל-API באמצעות 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
          ]
      }
    ]
  }'

מבנה גוף התשובה

גוף התשובה דומה גם במצב סטרימינג וגם במצב רגיל, למעט המקרים הבאים:

באופן כללי, גוף התשובה מכיל אובייקט 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. ממשק ה-API ישתמש בהיסטוריה הזו כהקשר לתשובה הבאה. הערך של 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"
}

‫Live API (BidiGenerateContent) WebSockets API

‫Live API הוא ממשק API מבוסס WebSocket עם שמירת מצב, שמאפשר סטרימינג דו-כיווני כדי להפעיל תרחישי שימוש של סטרימינג בזמן אמת. פרטים נוספים מופיעים במדריך לשימוש ב-Live API ובהפניה ל-Live API.

מודלים ייעודיים

בנוסף למשפחת המודלים של Gemini, ‏ Gemini API מציע נקודות קצה (endpoints) למודלים ייעודיים כמו Imagen,‏ Lyria ומודלים של embedding. אפשר לעיין במדריכים האלה בקטע 'מודלים'.

ממשקי API של הפלטפורמה

שאר נקודות הקצה מאפשרות להשתמש ביכולות נוספות עם נקודות הקצה העיקריות שתוארו עד עכשיו. מידע נוסף זמין בנושאים Batch mode ו-File API בקטע Guides.

המאמרים הבאים

אם אתם רק מתחילים, כדאי לעיין במדריכים הבאים שיעזרו לכם להבין את מודל התכנות של Gemini API:

כדאי גם לעיין במדריכים ליכולות, שכוללים הסברים על תכונות שונות של Gemini API ודוגמאות קוד: