שימוש במפתחות API של Gemini

כדי להשתמש ב-Gemini API, צריך לאמת את הבקשות. אפשר לבצע אימות באמצעות מפתח API רגיל או מפתח API להרשאה.

איך יוצרים מפתח Gemini API או צופים בו

סוגי מפתחות API: רגיל לעומת הרשאה

מפתחות API מספקים גישה ל-Gemini API, אבל מאפייני האבטחה שלהם שונים. אנחנו מעבירים את Gemini API ממפתחות API רגילים למפתחות הרשאה כדי לשפר את האבטחה:

• מפתחות API רגילים: משייכים בקשות לפרויקט בענן ב-Google Cloud לצורכי חיוב ומכסה. מפתחות רגילים לא מזהים את היישות שקוראת ל-API, ולכן הם לא יכולים לתמוך בהרשאות ובבקרת גישה ברמת פירוט גבוהה.
• מפתחות הרשאה (auth): מקושרים ישירות לחשבון שירות של Google Cloud. כשמשתמשים במפתח הרשאה, הבקשות מעובדות תחת הזהות של חשבון השירות המקושר, וכך מתאפשרת שליטה מדויקת בגישה. כברירת מחדל, מפתחות הרשאה מוגבלים ל-Generative Language API ‏(Gemini API) ומספקים אכיפה מהירה של מפתחות שנחשפו, שמפסיקה במהירות את השימוש במפתחות שנחשפו שזוהו על ידי המערכות שלנו.

כדי להבטיח שימוש מאובטח, Gemini API יעבור ממפתחות רגילים למפתחות אימות:

• ברירת המחדל של מפתחות אימות: כל מפתחות ה-API החדשים שנוצרים ב-Google AI Studio נוצרים אוטומטית כמפתחות אימות.
• ב-19 ביוני 2026: Gemini API ידחה בקשות ממפתחות רגילים ללא הגבלות. מפתחות API רגילים שהוחלו עליהם הגבלות מפורשות ימשיכו לפעול. ההגבלה הזו מונעת שימוש לא מורשה במפתחות שאולי שותפו באופן ציבורי או מקושרים לשירותים אחרים.
• בספטמבר 2026: Gemini API ידחה בקשות ממפתחות רגילים. כדי למנוע שיבושים בשירות, עליך לעבור למפתחות אימות לפני התאריך הזה. חשוב להעביר את המינוי למפתחות אימות לפני ספטמבר 2026.

ניהול מפתחות API ב-Google AI Studio

אתם יכולים לנהל את הפרויקטים והמפתחות שלכם ישירות ב-Google AI Studio.

פרויקטים ב-Google Cloud

כל מפתח Gemini API משויך לפרויקט בענן של Google. בפרויקטים ב-Google Cloud מנהלים את החיוב, את שותפי העריכה ואת ההרשאות. ‫Google AI Studio מספק ממשק קל משקל לגישה לפרויקטים האלה.

• פרויקט שמוגדר כברירת מחדל: אם אתם משתמשים חדשים, Google AI Studio יוצר באופן אוטומטי פרויקט בענן ב-Google Cloud ומפתח API שמוגדרים כברירת מחדל אחרי שאתם מאשרים את התנאים וההגבלות. כדי לשנות את שם הפרויקט, עוברים לתצוגה Projects במרכז הבקרה.
• פרויקטים קיימים: אם כבר יש לכם חשבון Google Cloud, ‏ AI Studio לא יוצר פרויקט ברירת מחדל. במקום זאת, צריך לייבא את הפרויקטים הקיימים.

ייבוא פרויקטים

כברירת מחדל, לא כל הפרויקטים שלכם ב-Google Cloud מוצגים ב-Google AI Studio. צריך לייבא את הפרויקטים שרוצים להשתמש בהם:

1. עוברים אל Google AI Studio.
2. פותחים את לוח הבקרה בחלונית הימנית ובוחרים באפשרות פרויקטים.
3. לוחצים על הלחצן ייבוא פרויקטים.
4. מחפשים את פרויקט הענן ב-Google Cloud שרוצים לייבא ובוחרים אותו, ואז לוחצים על ייבוא.
5. אחרי הייבוא, עוברים לדף מפתחות API במרכז הבקרה כדי ליצור מפתח בפרויקט הזה.

פתרון בעיות בהרשאות ליצירת מפתחות

אם הלחצן יצירת מפתח API לא זמין ומוצגת ההודעה: "אין לך הרשאה ליצור מפתח בפרויקט הזה", סימן שאין לך את הרשאות IAM הנדרשות.

מבקשים מהאדמין של פרויקט בענן או הארגון ב-Google Cloud להקצות לכם תפקיד שמכיל את ההרשאות הבאות (למשל, Project Editor):

• ‫resourcemanager.projects.get: מאפשר ל-AI Studio לאמת את הפרויקט.
• ‫apikeys.keys.create: מאפשר יצירת מפתחות.
• ‫serviceusage.services.enable: מוודא שממשק Generative Language API מופעל.
• iam.serviceAccounts.create: חובה כדי ליצור את חשבון השירות המקושר.
• ‫iam.serviceAccountApiKeyBindings.create: קושר את חשבון השירות למפתח ה-API.

אם אין לכם אפשרות לקבל הרשאת גישה אדמיניסטרטיבית, אתם יכולים ליצור פרויקט חדש ב-Google Cloud שלא משויך לארגון כדי ליצור את המפתחות.

הגדרת הסביבה

אחרי שיש לכם מפתח, אתם צריכים להגדיר את הסביבה כך שהמפתח ישמש את האפליקציות שלכם בצורה מאובטחת.

שימוש במשתני סביבה (מומלץ)

מגדירים את משתנה הסביבה GEMINI_API_KEY או GOOGLE_API_KEY. ספריות הלקוח של Gemini API מזהות את המשתנים האלה ומשתמשות בהם באופן אוטומטי. אם שתי ההגדרות מוגדרות, GOOGLE_API_KEY מקבל עדיפות.

בוחרים את מערכת ההפעלה כדי להגדיר את המשתנה:

~/.bashrc

touch ~/.bashrc && open ~/.bashrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.bashrc

~/.zshrc

touch ~/.zshrc && open ~/.zshrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.zshrc

ציון מפתח ה-API באופן מפורש בקוד

אפשר להעביר את מפתח ה-API באופן מפורש כשמאתחלים את הלקוח. כדאי לעשות את זה רק אם אי אפשר להשתמש במשתני סביבה.

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how AI works in a few words"
)
print(response.text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

main();

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey:  "YOUR_API_KEY",
        Backend: genai.BackendGeminiAPI,
    })
    if err != nil {
        log.Fatal(err)
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.5-flash",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

package com.example;

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().apiKey("YOUR_API_KEY").build();

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-3.5-flash",
            "Explain how AI works in a few words",
            null);

    System.out.println(response.text());
  }
}

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent"       -H 'Content-Type: application/json'       -H "x-goog-api-key: YOUR_API_KEY"       -X POST       -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

אבטחה וניהול סודות

מפתח ה-API של Gemini הוא כמו סיסמה. אם פרטי הכניסה נחשפו, אנשים אחרים יכולים לנצל את המכסה של הפרויקט, לגרום לחיובים לא צפויים ולגשת למשאבים פרטיים.

כללי אבטחה קריטיים

• שומרים על סודיות המפתחות: לעולם אל תבדקו מפתחות API במערכות לניהול גרסאות כמו Git.
• לעולם אל תחשפו מפתחות בצד הלקוח בסביבת ייצור: אל תקודדו מפתחות API ישירות באפליקציות לאינטרנט או לנייד. משתמשים יכולים לחלץ מפתחות שקומפלו בקוד בצד הלקוח. כדי לאבטח אפליקציות בצד הלקוח, מריצים שרת proxy של בק-אנד כדי לבצע את הקריאות בפועל ל-API.

שיטות מומלצות לניהול סודות

• משתני סביבה: קריאת מפתחות ממשתני סביבה במקום מקובצי תצורה.
• ‫Secret Manager: בסביבת ייצור, מומלץ לאחסן את המפתחות במאגר סודי מאובטח כמו Google Cloud Secret Manager.
• התראות על חיוב: אפשר להגדיר התראות על חיוב ב-Google Cloud Console כדי לקבל הודעה אם יש עלייה חדה בשימוש או בעלויות.

רשימת משימות לתגובה על דליפת נתונים

אם אתם חושדים שמפתח ה-API שלכם דלף:

1. יצירת מפתח חדש: יוצרים מפתח חלופי ב-Google AI Studio או ב-Cloud Console.
2. מעדכנים את האפליקציה: פורסים את הקוד באמצעות המפתח החדש.
3. משביתים או מוחקים את המפתח שנפרץ: אחרי שהמפתח החדש מאומת, משביתים את המפתח שנפרץ במסוף Cloud. כדי למנוע השבתה של האפליקציה, אל תמחקו את המפתח הישן עד שהמפתח החדש יהיה פעיל לגמרי.
4. בדיקת השימוש: כדי לזהות פעילות לא מורשית, בודקים את יומני החיוב ואת השימוש ב-API במסוף Google Cloud.

הגבלת הגישה למפתחות והגנה עליהם

הוספת הגבלות למפתחות ה-API מצמצמת את הנזק הפוטנציאלי אם מפתח נפרץ.

החלת הגבלות על מקור הבקשה

הגבלות על מקורות מגבילות את כתובות ה-IP, האתרים או האפליקציות שיכולים להשתמש במפתח.

1. נכנסים אל הדף Credentials במסוף Google Cloud.
2. בוחרים את הפרויקט ולוחצים על השם של מפתח ה-API שרוצים להגביל.
3. בקטע Application restrictions, בוחרים באפשרות IP addresses (או בסוג ההגבלה המתאים לסביבה שלכם).
4. מציינים את כתובות ה-IP או את טווחי כתובות ה-IP המותרים ולוחצים על שמירה.

אבטחה של מפתחות API רגילים ללא הגבלות

כדי להמשיך להשתמש ב-Gemini API אחרי 19 ביוני 2026, צריך לאבטח את כל המפתחות הלא מוגבלים.

הגבלת המפתח ל-Gemini API בלבד דרך AI Studio

אם אתם משתמשים במפתח רק עבור Gemini API, אתם יכולים לאבטח אותו ישירות ב-AI Studio:

1. בדף API Keys ב-Google AI Studio, מאתרים מפתחות שמסומנים בתווית Unrestricted.
2. מעבירים את העכבר מעל התווית ולוחצים על הוספת הגבלות בתיבת הדו-שיח.
3. בוחרים באפשרות הגבלה ל-Gemini API בלבד.
4. לוחצים על הגבלת המפתח כדי לאשר.

הגבלת המפתח לשירותים אחרים דרך מסוף Google Cloud

אם המפתח משותף עם ממשקי Google API אחרים (לא מומלץ), צריך להגביל אותו במסוף Cloud. הערה: בקשות ל-Gemini API באמצעות המפתח הזה ייכשלו אחרי החלת ההגבלות האלה.

1. נכנסים אל הדף Credentials במסוף Google Cloud.
2. בוחרים את הפרויקט ואת מפתח ה-API.
3. בקטע API restrictions, בוחרים באפשרות Restrict key.
4. בתפריט הנפתח, בוחרים את ממשקי ה-API שרוצים שהמפתח הזה יוכל לגשת אליהם. לא בוחרים באפשרות Generative Language API.
5. לוחצים על שמירה. כדי להמשיך להשתמש ב-Gemini API, צריך ליצור מפתח נפרד ומוגבל ב-AI Studio.

חסימה של מפתחות לא פעילים

החל מ-7 במאי 2026, Gemini API יחסום מפתחות API ללא הגבלות שלא נעשה בהם שימוש במשך תקופה ארוכה. המפתחות האלה יסומנו בתג Blocked ב-AI Studio. כדי להמשיך להשתמש ב-API, תצטרכו ליצור מפתח חדש או להשתמש במפתח קיים עם הגבלות.

מעבר למפתח אימות

כדי ליצור מפתח API חדש לאימות ולעדכן את האפליקציות:

1. עוברים אל דף מפתחות ה-API של AI Studio.
2. בודקים את העמודה סוג המפתח כדי לזהות מפתחות שמופיעים כרגילים.
3. לוחצים על Create API key כדי ליצור מפתח חדש. כל המפתחות החדשים שנוצרים ב-AI Studio נוצרים אוטומטית כמפתחות אימות.
4. מעתיקים את מפתח ה-API החדש לאימות.
5. מעדכנים את קוד האפליקציה, את משתני הסביבה ואת כל הגדרות הפריסה כך שישתמשו במפתח ה-API החדש לאימות.
6. בודקים את האפליקציה כדי לוודא שהיא פועלת בצורה תקינה עם המפתח החדש.
7. אחרי האימות, מוחקים או מבטלים את מפתח התעבורה הישן כדי למנוע שימוש לרעה.

מגבלות

יש מגבלות על ניהול פרויקטים ומפתחות ב-Google AI Studio:

• אפשר ליצור עד 10 פרויקטים בכל פעם מדף Projects ב-Google AI Studio.
• בדפים API keys ו-Projects מוצגים עד 100 מפתחות ו-50 פרויקטים.
• מוצגים רק מפתחות API שלא הוגבלו או שהוגבלו ספציפית ל-Generative Language API (Gemini API).

לניהול מתקדם של פרויקטים או לשינוי מפתחות עם הגבלות אחרות, אפשר להשתמש בדף פרטי הכניסה במסוף Google Cloud.