Gemini API reference

במסמך הזה מפורטות הפונקציות של ממשקי ה-API הרגילים, של ממשקי ה-API להזרמת נתונים ושל ממשקי ה-API בזמן אמת, שבהם אפשר להשתמש כדי ליצור אינטראקציה עם המודלים של Gemini. אפשר להשתמש בממשקי ה-API של REST בכל סביבה שתומכת בבקשות HTTP. במדריך למתחילים מוסבר איך להתחיל עם הקריאה הראשונה ל-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, ואפשר לגשת אליהן באמצעות generateContentAPI.
‫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 SDKs זמינות במדריך שימוש במפתחות 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. ממשק ה-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.
ניהול היסטוריית השיחות: באפליקציות צ'אט שמשתמשות ב-API ל-REST, צריך ליצור את המערך 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 ודוגמאות קוד: