שיטות קלט של קבצים

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

הדרך הכי פשוטה לכלול קובץ כקלט היא לקרוא קובץ מקומי ולכלול אותו בהנחיה. בדוגמה הבאה אפשר לראות איך קוראים קובץ PDF מקומי. בשיטה הזו, גודל קובצי ה-PDF מוגבל ל-50MB. רשימה מלאה של סוגי קבצים ומגבלות מופיעה בטבלת ההשוואה של שיטות הקלט.

Python

from google import genai
from google.genai import types
import pathlib

client = genai.Client()

filepath = pathlib.Path('my_local_file.pdf')

prompt = "Summarize this document"
response = client.models.generate_content(
  model="gemini-3-flash-preview",
  contents=[
      types.Part.from_bytes(
        data=filepath.read_bytes(),
        mime_type='application/pdf',
      ),
      prompt
  ]
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from 'node:fs';

const ai = new GoogleGenAI({});
const prompt = "Summarize this document";

async function main() {
    const filePath = path.join('content', 'my_local_file.pdf'); // Adjust path as needed

    const contents = [
        { text: prompt },
        {
            inlineData: {
                mimeType: 'application/pdf',
                data: fs.readFileSync(filePath).toString("base64")
            }
        }
    ];

    const response = await ai.models.generateContent({
        model: "gemini-3-flash-preview",
        contents: contents
    });
    console.log(response.text);
}

main();

REST

# Encode the local file to base64
B64_CONTENT=$(base64 -w 0 my_local_file.pdf)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "Summarize this document"}
        ]
      },
      {
        "parts": [
          {
            "inlineData": {
              "mimeType": "application/pdf",
              "data": "'"${B64_CONTENT}"'"
            }
          }
        ]
      }
    ]
  }'

השוואה בין שיטות קלט

בטבלה הבאה מוצגת השוואה בין כל שיטות הקלט, עם מגבלות הקבצים והתרחישים המומלצים לשימוש. שימו לב שמגבלת גודל הקובץ עשויה להשתנות בהתאם לסוג הקובץ ולמודל או לטוקנייזר שמשמשים לעיבוד הקובץ.

שיטה	הכי טוב עבור	גודל קובץ מקסימלי	התמדה
נתונים מוטבעים	בדיקה מהירה, קבצים קטנים, אפליקציות בזמן אמת.	‫100MB לכל בקשה או מטען ייעודי (payload) (50MB לקובצי PDF)	ללא (נשלח עם כל בקשה)
העלאה דרך File API	קבצים גדולים, קבצים שנעשה בהם שימוש כמה פעמים.	‫2GB לכל קובץ, עד 20GB לכל פרויקט	‫48 שעות
רישום של URI של GCS ב-File API	קבצים גדולים שכבר נמצאים ב-Google Cloud Storage, קבצים שנמצאים בשימוש כמה פעמים.	‫2GB לכל קובץ, ללא מגבלות אחסון כוללות	ללא (מאוחזר לכל בקשה). רישום חד-פעמי יכול להעניק גישה למשך עד 30 יום.
כתובות URL חיצוניות	נתונים ציבוריים או נתונים בקטגוריות של Cloud (AWS, ‏ Azure, ‏ GCS) בלי להעלות אותם מחדש.	‫100MB לכל בקשה או מטען ייעודי (payload)	ללא (מאוחזר לפי בקשה)

נתונים בתוך השורה

אם הקבצים קטנים (עד 100MB, או עד 50MB לקובצי PDF), אפשר להעביר את הנתונים ישירות במטען הייעודי (payload) של הבקשה. זו השיטה הפשוטה ביותר לבדיקות מהירות או לאפליקציות שמטפלות בנתונים זמניים בזמן אמת. אפשר לספק נתונים כמחרוזות מקודדות ב-Base64 או על ידי קריאה ישירה של קבצים מקומיים.

דוגמה לקריאה מקובץ מקומי מופיעה בתחילת הדף הזה.

אחזור מכתובת URL

אפשר גם לאחזר קובץ מכתובת URL, להמיר אותו לבייטים ולכלול אותו בקלט.

Python

from google import genai
from google.genai import types
import httpx

client = genai.Client()

doc_url = "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
doc_data = httpx.get(doc_url).content

prompt = "Summarize this document"

response = client.models.generate_content(
  model="gemini-3-flash-preview",
  contents=[
      types.Part.from_bytes(
        data=doc_data,
        mime_type='application/pdf',
      ),
      prompt
  ]
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});
const docUrl = 'https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf';
const prompt = "Summarize this document";

async function main() {
    const pdfResp = await fetch(docUrl);
      .then((response) => response.arrayBuffer());

    const contents = [
        { text: prompt },
        {
            inlineData: {
                mimeType: 'application/pdf',
                data: Buffer.from(pdfResp).toString("base64")
            }
        }
    ];

    const response = await ai.models.generateContent({
        model: "gemini-3-flash-preview",
        contents: contents
    });
    console.log(response.text);
}

main();

REST

DOC_URL="https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
PROMPT="Summarize this document"
DISPLAY_NAME="base64_pdf"

# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"

# Check for FreeBSD base64 and set flags accordingly
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

# Base64 encode the PDF
ENCODED_PDF=$(base64 $B64FLAGS "${DISPLAY_NAME}.pdf")

# Generate content using the base64 encoded PDF
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"inline_data": {"mime_type": "application/pdf", "data": "'"$ENCODED_PDF"'"}},
          {"text": "'$PROMPT'"}
        ]
      }]
    }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

Gemini File API

ממשק File API מיועד לקבצים גדולים יותר (עד 2GB) או לקבצים שרוצים להשתמש בהם בכמה בקשות.

העלאה רגילה של קבצים

מעלים קובץ מקומי ל-Gemini API. קבצים שמועלים בדרך הזו מאוחסנים באופן זמני (למשך 48 שעות) ומעובדים כדי שהמודל יוכל לאחזר אותם ביעילות.

Python

from google import genai
client = genai.Client()

# Upload the file
audio_file = client.files.upload(file="path/to/your/sample.mp3")
prompt = "Describe this audio clip"

# Use the uploaded file in a prompt
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[prompt, audio_file]
)
print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});
const prompt = "Describe this audio clip";

async function main() {
  const filePath = "path/to/your/sample.mp3"; // Adjust path as needed

  const myfile = await ai.files.upload({
    file: filePath,
    config: { mimeType: "audio/mpeg" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: createUserContent([
      prompt,
      createPartFromUri(myfile.uri, myfile.mimeType),
    ]),
  });
  console.log(response.text);

}
await main();

REST

AUDIO_PATH="path/to/sample.mp3"
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D "${tmp_header_file}" \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Describe this audio clip"},
          {"file_data":{"mime_type": "${MIME_TYPE}", "file_uri": '$file_uri'}}]
        }]
      }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

רישום קבצים ב-Google Cloud Storage

אם הנתונים שלכם כבר נמצאים ב-Google Cloud Storage, אתם לא צריכים להוריד אותם ולהעלות אותם מחדש. אפשר לרשום אותו ישירות באמצעות File API.

נותנים לסוכן השירות גישה לכל קטגוריה
1. מפעילים את Gemini API בפרויקט ב-Google Cloud.
2. יוצרים את סוכן השירות:
  
  gcloud beta services identity create --service=generativelanguage.googleapis.com --project=<your_project>
3. נותנים לסוכן השירות של Gemini API הרשאות לקריאה של קטגוריות האחסון.
  
  המשתמש צריך להקצות את Storage Object Viewer תפקיד ה-IAM לסוכן השירות הזה בקטגוריות האחסון הספציפיות שהוא מתכוון להשתמש בהן.
הגישה הזו לא פגה כברירת מחדל, אבל אפשר לשנות את זה בכל שלב. אפשר גם להשתמש בפקודות של Google Cloud Storage IAM SDK כדי להעניק הרשאות.
אימות השירות

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

מחוץ ל-Google Cloud

אם הקוד שלכם פועל מחוץ ל-Google Cloud, למשל מהמחשב, אתם צריכים להוריד את פרטי הכניסה לחשבון מ-Google Cloud Console באמצעות השלבים הבאים:
1. עוברים אל מסוף חשבון השירות.
2. בוחרים את חשבון השירות הרלוונטי.
3. בוחרים בכרטיסייה Keys ואז באפשרות Add key, Create new key.
4. בוחרים את סוג המפתח JSON ורושמים את המיקום במחשב שאליו הקובץ ירד.
פרטים נוספים זמינים במאמרי העזרה הרשמיים של Google Cloud בנושא ניהול מפתחות של חשבונות שירות.

אחר כך משתמשים בפקודות הבאות כדי לבצע אימות. הפקודות האלה מניחות שקובץ חשבון השירות נמצא בספרייה הנוכחית, ושמו service-account.json.
Python
```
from google.oauth2.service_account import Credentials

GCS_READ_SCOPES = [       
  'https://www.googleapis.com/auth/devstorage.read_only',
  'https://www.googleapis.com/auth/cloud-platform'
]

SERVICE_ACCOUNT_FILE = 'service-account.json'

credentials = Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE,
    scopes=GCS_READ_SCOPES
)
```
JavaScript
```
const { GoogleAuth } = require('google-auth-library');

const GCS_READ_SCOPES = [
  'https://www.googleapis.com/auth/devstorage.read_only',
  'https://www.googleapis.com/auth/cloud-platform'
];

const SERVICE_ACCOUNT_FILE = 'service-account.json';

const auth = new GoogleAuth({
  keyFile: SERVICE_ACCOUNT_FILE,
  scopes: GCS_READ_SCOPES
});
```
CLI
```
gcloud auth application-default login \
  --client-id-file=service-account.json \
  --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only'
```
ב-Google Cloud

אם אתם מריצים את הקוד ישירות ב-Google Cloud, למשל באמצעות פונקציות של Cloud Run או מכונה של Compute Engine, יהיו לכם פרטי כניסה מרומזים, אבל תצטרכו לבצע אימות מחדש כדי להעניק את ההיקפים המתאימים.
Python
הקוד הזה מניח שהשירות פועל בסביבה שבה אפשר לקבל באופן אוטומטי אישורים שמוגדרים כברירת מחדל לאפליקציה, כמו Cloud Run או Compute Engine.
```
import google.auth

GCS_READ_SCOPES = [       
  'https://www.googleapis.com/auth/devstorage.read_only',
  'https://www.googleapis.com/auth/cloud-platform'
]

credentials, project = google.auth.default(scopes=GCS_READ_SCOPES)
```
JavaScript
הקוד הזה מניח שהשירות פועל בסביבה שבה אפשר לקבל באופן אוטומטי אישורים שמוגדרים כברירת מחדל לאפליקציה, כמו Cloud Run או Compute Engine.
```
const { GoogleAuth } = require('google-auth-library');

const auth = new GoogleAuth({
  scopes: [
    'https://www.googleapis.com/auth/devstorage.read_only',
    'https://www.googleapis.com/auth/cloud-platform'
  ]
});
```
CLI
זוהי פקודה אינטראקטיבית. בשירותים כמו Compute Engine, אפשר לצרף היקפי הרשאות לשירות הפועל ברמת ההגדרה. דוגמה מופיעה במסמכים בנושא שירותים בניהול המשתמשים.
```
gcloud auth application-default login \
--scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only"
```

רישום קבצים (Files API)

משתמשים ב-Files API כדי לרשום קבצים וליצור נתיב Files API שאפשר להשתמש בו ישירות ב-Gemini API.

Python

from google import genai
from google.genai.types import Part

# Note that you must provide an API key in the GEMINI_API_KEY
# environment variable, but it is unused for the registration endpoint.
client = genai.Client()

registered_gcs_files = client.files.register_files(
    uris=["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"],
    # Use the credentials obtained in the previous step.
    auth=credentials
)
prompt = "Summarize this file."

# call generateContent for each file
for f in registered_gcs_files.files:
  print(f.name)
  response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[Part.from_uri(
      file_uri=f.uri,
      mime_type=f.mime_type,
    ),
    prompt],
  )
  print(response.text)

CLI

access_token=$(gcloud auth application-default print-access-token)
project_id=$(gcloud config get-value project)
curl -X POST https://generativelanguage.googleapis.com/v1beta/files:register \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ${access_token}" \
    -H "x-goog-user-project: ${project_id}" \
    -d '{"uris": ["gs://bucket/object1", "gs://bucket/object2"]}'

כתובות URL חיצוניות מסוג HTTP / כתובות URL חתומות

אפשר להעביר כתובות URL מסוג HTTPS שנגישות לכולם או כתובות URL חתומות מראש (שמתאימות לכתובות URL חתומות מראש של S3 ול-SAS של Azure) ישירות בבקשת היצירה. ‫Gemini API יאחזר את התוכן באופן מאובטח במהלך העיבוד. האפשרות הזו מתאימה לקבצים בגודל של עד 100MB שלא רוצים להעלות מחדש.

אפשר להשתמש בכתובות URL ציבוריות או חתומות כקלט באמצעות כתובות ה-URL בשדה file_uri.

Python

from google import genai
from google.genai.types import Part

uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf"
prompt = "Summarize this file"

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[
        Part.from_uri(
            file_uri=uri,
            mime_type="application/pdf",
        ),
        prompt
    ],
)
print(response.text)

JavaScript

import { GoogleGenAI, createPartFromUri } from '@google/genai';

const client = new GoogleGenAI({});

const uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf";

async function main() {
  const response = await client.models.generateContent({
    model: 'gemini-3-flash-preview',
    contents: [
      // equivalent to Part.from_uri(file_uri=uri, mime_type="...")
      createPartFromUri(uri, "application/pdf"),
      "summarize this file",
    ],
  });

  console.log(response.text);
}

main();

REST

curl "https://autopush-generativelanguage.sandbox.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent \
      -H 'x-goog-api-key: $GEMINI_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
          "contents":[
            {
              "parts":[
                {"text": "Summarize this pdf"},
                {
                  "file_data": {
                    "mime_type":"application/pdf",
                    "file_uri": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf"
                  }
                }
              ]
            }
          ]
        }'

נגישות

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

בדיקות אבטחה

המערכת מבצעת בדיקה של ניהול התוכן בכתובת ה-URL כדי לוודא שהיא עומדת בתקני הבטיחות והמדיניות (למשל, תוכן שלא בוטלה ההסכמה שלו ושהגישה אליו מוגבלת בתשלום). אם כתובת ה-URL שסיפקתם לא תעבור את הבדיקה הזו, תקבלו הודעה על url_retrieval_status מתוך URL_RETRIEVAL_STATUS_UNSAFE.

סוגי התוכן הנתמכים

הרשימה הזו של סוגי קבצים נתמכים ומגבלות נועדה לספק הנחיות ראשוניות, והיא לא מקיפה. קבוצת הסוגים הנתמכים בפועל עשויה להשתנות, והיא תלויה במודל הספציפי ובגרסת הטוקנייזר שנמצאים בשימוש. סוגים שלא נתמכים יגרמו לשגיאה. בנוסף, אחזור תוכן עבור סוגי הקבצים האלה תומך כרגע רק בכתובות URL שזמינות לכל.

סוגים של קובצי טקסט

text/html
text/css
text/plain
text/xml
text/scv
text/rtf
text/javascript

סוגי קבצים של אפליקציות

application/json
application/pdf

סוגים של קובצי תמונות

image/bmp
image/jpeg
image/png
image/webp

שיטות מומלצות

בחירת השיטה הנכונה: משתמשים בנתונים מוטבעים לקבצים קטנים וזמניים. כדאי להשתמש ב-File API לקבצים גדולים או לקבצים שנמצאים בשימוש תדיר. שימוש בכתובות URL חיצוניות לנתונים שכבר מתארחים אונליין.
צריך לציין סוגי MIME: כדי להבטיח עיבוד תקין, צריך תמיד לציין את סוג ה-MIME הנכון של נתוני הקובץ.
טיפול בשגיאות: כדאי להטמיע טיפול בשגיאות בקוד כדי לנהל בעיות פוטנציאליות כמו כשלים ברשת, בעיות בגישה לקבצים או שגיאות ב-API.
ניהול הרשאות GCS: כשמשתמשים ברישום GCS, צריך להעניק לסוכן השירות של Gemini API רק את התפקיד Storage Object Viewer הנדרש בקטגוריות הספציפיות.
אבטחת כתובות URL חתומות: מוודאים שלכתובות URL חתומות יש זמן תפוגה מתאים והרשאות מוגבלות.

מגבלות

מגבלות גודל הקובץ משתנות בהתאם לשיטה (ראו טבלת השוואה) וסוג הקובץ.
נתונים מוטבעים מגדילים את הגודל של מטען ייעודי (payload) של הבקשה.
העלאות באמצעות File API הן זמניות והתוקף שלהן פג אחרי 48 שעות.
הגודל של מטען ייעודי (payload) שמתקבל מכתובת URL חיצונית מוגבל ל-100MB, והוא תומך בסוגי תוכן ספציפיים.
כדי להירשם ל-Google Cloud Storage, צריך להגדיר את IAM בצורה נכונה ולנהל את אסימוני OAuth.

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

אתם יכולים לנסות לכתוב הנחיות מולטימודאליות משלכם באמצעות Google AI Studio.
מידע על הכללת קבצים בהנחיות זמין במדריכים בנושא Vision,‏ Audio ועיבוד מסמכים.
לקבלת הנחיות נוספות בנושא עיצוב הנחיות, כמו כוונון פרמטרים של דגימה, אפשר לעיין במדריך אסטרטגיות להנחיות.