שיטות קלט של קבצים
במדריך הזה מוסברות הדרכים השונות שבהן אפשר לכלול קובצי מדיה כמו תמונות, אודיו, וידאו ומסמכים כששולחים בקשות ל-Gemini API. השיטות החדשות נתמכות בכל נקודות הקצה (endpoints) של Gemini API, כולל Batch, Interactions ו-Live API. השיטה שתבחרו תלויה בגודל הקובץ, במיקום שבו הנתונים מאוחסנים ובתדירות שבה אתם מתכננים להשתמש בקובץ.
הדרך הכי פשוטה לכלול קובץ כקלט היא לקרוא קובץ מקומי ולכלול אותו בהנחיה. בדוגמה הבאה אפשר לראות איך קוראים קובץ PDF מקומי. בשיטה הזו, גודל קובצי ה-PDF מוגבל ל-50MB. רשימה מלאה של סוגי קבצים ומגבלות מופיעה בטבלת ההשוואה של שיטות הקלט.
Python
from google import genai
import pathlib
client = genai.Client()
filepath = pathlib.Path('my_local_file.pdf')
prompt = "Summarize this document"
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{"type": "text", "text": prompt},
{"type": "document", "data": filepath.read_bytes(), "mime_type": "application/pdf"}
]
)
# Print the model's text response
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
JavaScript
import { GoogleGenAI } from "@google/genai";
import * as fs from 'node:fs';
const client = new GoogleGenAI({});
const prompt = "Summarize this document";
async function main() {
const filePath = 'my_local_file.pdf';
const interaction = await client.interactions.create({
model: "gemini-3-flash-preview",
input: [
{ type: "text", text: prompt },
{
type: "document",
data: fs.readFileSync(filePath).toString("base64"),
mimeType: "application/pdf"
}
]
});
const modelStep = interaction.steps.find(s => s.type === 'model_output');
if (modelStep) {
for (const contentBlock of modelStep.content) {
if (contentBlock.type === 'text') console.log(contentBlock.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/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3-flash-preview",
"input": [
{"type": "text", "text": "Summarize this document"},
{
"type": "document",
"data": "'${B64_CONTENT}'",
"mimeType": "application/pdf"
}
]
}'
השוואה בין שיטות קלט
בטבלה הבאה מוצגת השוואה בין כל שיטות הקלט, עם מגבלות הקבצים והתרחישים המומלצים לשימוש. שימו לב שמגבלת גודל הקובץ עשויה להשתנות בהתאם לסוג הקובץ ולמודל או לטוקנייזר שמשמשים לעיבוד הקובץ.
| שיטה | הכי טוב עבור | גודל קובץ מקסימלי | התמדה |
|---|---|---|---|
| נתונים מוטבעים | בדיקה מהירה, קבצים קטנים, אפליקציות בזמן אמת. | 100MB לכל בקשה או מטען ייעודי (50MB לקובצי PDF) |
ללא (נשלח עם כל בקשה) |
| העלאת קובץ דרך API | קבצים גדולים, קבצים שנעשה בהם שימוש כמה פעמים. | 2GB לכל קובץ, עד 20GB לכל פרויקט |
48 שעות |
| רישום של URI של GCS ב-File API | קבצים גדולים שכבר נמצאים ב-Google Cloud Storage, קבצים שנמצאים בשימוש כמה פעמים. | 2GB לכל קובץ, ללא מגבלות אחסון כוללות | ללא (מאוחזר לכל בקשה). רישום חד-פעמי יכול להעניק גישה למשך 30 יום לכל היותר. |
| כתובות URL חיצוניות | נתונים ציבוריים או נתונים בדליים בענן (AWS, Azure, GCS) בלי להעלות אותם מחדש. | 100MB לכל בקשה או מטען ייעודי (payload) | ללא (מאוחזר לפי בקשה) |
נתונים מוטבעים
אם הקבצים קטנים (עד 100MB, או עד 50MB לקובצי PDF), אפשר להעביר את הנתונים ישירות במטען הייעודי (payload) של הבקשה. זו השיטה הפשוטה ביותר לבדיקות מהירות או לאפליקציות שמטפלות בנתונים זמניים בזמן אמת. אפשר לספק נתונים כמחרוזות מקודדות ב-Base64 או על ידי קריאה ישירה של קבצים מקומיים.
דוגמה לקריאה מקובץ מקומי מופיעה בתחילת הדף הזה.
אחזור מכתובת URL
אפשר גם לאחזר קובץ מכתובת URL, להמיר אותו לבייטים ולכלול אותו בקלט.
Python
from google import genai
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"
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{"type": "document", "data": doc_data, "mime_type": "application/pdf"},
{"type": "text", "text": prompt}
]
)
# Print the model's text response
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = 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 interaction = await client.interactions.create({
model: "gemini-3-flash-preview",
input: [
{ type: "text", text: prompt },
{
type: "document",
data: Buffer.from(pdfResp).toString("base64"),
mimeType: "application/pdf"
}
]
});
const modelStep = interaction.steps.find(s => s.type === 'model_output');
if (modelStep) {
for (const contentBlock of modelStep.content) {
if (contentBlock.type === 'text') console.log(contentBlock.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 interactions
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3-flash-preview",
"input": [
{"type": "document", "data": "'$ENCODED_PDF'", "mimeType": "application/pdf"},
{"type": "text", "text": "'$PROMPT'"}
]
}' 2> /dev/null > response.json
cat response.json
echo
jq ".steps[] | select(.type == \"model_output\") | .content[] | select(.type == \"text\") | .text" response.json
Gemini File API
ממשק ה-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 an interaction
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{"type": "text", "text": prompt},
{"type": "audio", "uri": audio_file.uri, "mime_type": audio_file.mime_type}
]
)
# Print the model's text response
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const prompt = "Describe this audio clip";
async function main() {
const filePath = "path/to/your/sample.mp3";
const myfile = await client.files.upload({
file: filePath,
config: { mimeType: "audio/mpeg" },
});
const interaction = await client.interactions.create({
model: "gemini-3-flash-preview",
input: [
{ type: "text", text: prompt },
{ type: "audio", uri: myfile.uri, mimeType: myfile.mimeType }
]
});
const modelStep = interaction.steps.find(s => s.type === 'model_output');
if (modelStep) {
for (const contentBlock of modelStep.content) {
if (contentBlock.type === 'text') console.log(contentBlock.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.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
-D "${tmp_header_file}" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-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)
# Now use in an interaction
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3-flash-preview",
"input": [
{"type": "text", "text": "Describe this audio clip"},
{"type": "audio", "uri": '$file_uri', "mimeType": "'${MIME_TYPE}'"}
]
}'
רישום קבצים ב-Google Cloud Storage
אם הנתונים שלכם כבר נמצאים ב-Google Cloud Storage, אתם לא צריכים להוריד אותם ולהעלות אותם מחדש. אפשר לרשום אותו ישירות באמצעות File API.
הענקת גישה לכל דלי לסוכן שירות
מפעילים את Gemini API בפרויקט בענן ב-Google Cloud.
יוצרים את סוכן השירות:
gcloud beta services identity create --service=generativelanguage.googleapis.com --project=<your_project>נותנים לסוכן השירות של Gemini API הרשאות לקריאה של קטגוריות האחסון.
המשתמש צריך להקצות את
Storage Object Viewerתפקיד ה-IAM לסוכן השירות הזה בקטגוריות האחסון הספציפיות שהוא מתכוון להשתמש בהן.
הגישה הזו לא פגה כברירת מחדל, אבל אפשר לשנות את זה בכל שלב. אפשר גם להשתמש בפקודות של Google Cloud Storage IAM SDK כדי להעניק הרשאות.
אימות השירות
דרישות מוקדמות
- הפעלת ה-API
- יוצרים חשבון שירות או סוכן עם ההרשאות המתאימות.
קודם צריך לבצע אימות כשירות שיש לו הרשאות לצפייה באובייקט אחסון. אופן הגבייה תלוי בסביבה שבה יפעל קוד ניהול הקבצים.
מחוץ ל-Google Cloud
אם הקוד שלכם מורץ מחוץ ל-Google Cloud, למשל מהמחשב, אתם צריכים להוריד את פרטי הכניסה לחשבון מ-Google Cloud Console. כך עושים את זה:
- עוברים אל מסוף חשבון השירות.
- בוחרים את חשבון השירות הרלוונטי.
- בוחרים בכרטיסייה Keys ואז באפשרות Add key, Create new key.
- בוחרים את סוג המפתח 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
הקוד הזה מניח שהשירות פועל בסביבה שבה אפשר לקבל אוטומטית Application Default Credentials, כמו 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
הקוד הזה מניח שהשירות פועל בסביבה שבה אפשר לקבל באופן אוטומטי Application Default Credentials, כמו 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 # 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(credentials=credentials) registered_gcs_files = client.files.register_files( uris=["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"] ) prompt = "Summarize this file." # call interactions.create for each file for f in registered_gcs_files.files: print(f.name) interaction = client.interactions.create( model="gemini-3-flash-preview", input=[ {"type": "text", "text": prompt}, {"type": "document", "uri": f.uri, "mime_type": f.mime_type} ], ) # Print the model's text response for step in interaction.steps: if step.type == "model_output": for content_block in step.content: if content_block.type == "text": print(content_block.text)JavaScript
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ auth: auth }); async function main() { const registeredGcsFiles = await ai.files.registerFiles({ uris: ["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"] }); const prompt = "Summarize this file."; for (const file of registeredGcsFiles.files) { console.log(file.name); const interaction = await ai.interactions.create({ model: "gemini-3-flash-preview", input: [ { type: "text", text: prompt }, { type: "document", uri: file.uri, mimeType: file.mimeType } ] }); const modelStep = interaction.steps.find(s => s.type === 'model_output'); if (modelStep) { for (const contentBlock of modelStep.content) { if (contentBlock.type === 'text') console.log(contentBlock.text); } } } } main();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 חתומות מראש ישירות בבקשה. Gemini API יאחזר את התוכן באופן מאובטח במהלך העיבוד. האפשרות הזו מתאימה לקבצים בגודל של עד 100MB שלא רוצים להעלות מחדש.
Python
from google import genai
uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf"
prompt = "Summarize this file"
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{"type": "document", "uri": uri, "mime_type": "application/pdf"},
{"type": "text", "text": prompt}
]
)
# Print the model's text response
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf";
async function main() {
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: [
{ type: "document", uri: uri, mimeType: "application/pdf" },
{ type: "text", text: "summarize this file" }
]
});
const modelStep = interaction.steps.find(s => s.type === 'model_output');
if (modelStep) {
for (const contentBlock of modelStep.content) {
if (contentBlock.type === 'text') console.log(contentBlock.text);
}
}
}
main();
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H 'x-goog-api-key: $GEMINI_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3-flash-preview",
"input": [
{"type": "text", "text": "Summarize this pdf"},
{
"type": "document",
"uri": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf",
"mimeType": "application/pdf"
}
]
}'
נגישות
מוודאים שכתובות ה-URL שציינתם לא מובילות לדפים שנדרשת בהם התחברות או לדפים שמוגנים על ידי חומת תשלום. במסדי נתונים פרטיים, חשוב לוודא שאתם יוצרים כתובת URL חתומה עם הרשאות הגישה ותאריך התפוגה הנכונים.
בדיקות אבטחה
המערכת מבצעת בדיקה של ניהול התוכן בכתובת ה-URL כדי לוודא שהיא עומדת בתקני הבטיחות והמדיניות. אם כתובת ה-URL תיכשל בבדיקה הזו, תקבלו הודעה
url_retrieval_status של URL_RETRIEVAL_STATUS_UNSAFE.
סוגי התוכן הנתמכים
הרשימה הזו של סוגי קבצים נתמכים ומגבלות נועדה לספק הנחיות ראשוניות, והיא לא מלאה. קבוצת הסוגים הנתמכים בפועל עשויה להשתנות, והיא תלויה במודל הספציפי ובגרסת הטוקנייזר שנמצאים בשימוש. סוגים שלא נתמכים יגרמו לשגיאה. בנוסף, אחזור תוכן עבור סוגי הקבצים האלה תומך רק בכתובות URL שזמינות לכל.
סוגים של קובצי טקסט
text/htmltext/csstext/plaintext/xmltext/csvtext/rtftext/javascript
סוגי קבצים של אפליקציות
application/jsonapplication/pdf
סוגים של קובצי תמונות
image/bmpimage/jpegimage/pngimage/webp
שיטות מומלצות
- בחירת השיטה הנכונה: משתמשים בנתונים מוטבעים לקבצים קטנים וזמניים. כדאי להשתמש ב-File API לקבצים גדולים או לקבצים שמשתמשים בהם לעיתים קרובות. שימוש בכתובות URL חיצוניות לנתונים שכבר מתארחים אונליין.
- מציינים סוגי MIME: חשוב לספק תמיד את סוג ה-MIME הנכון לנתוני הקובץ כדי להבטיח עיבוד תקין.
- טיפול בשגיאות: כדאי להטמיע טיפול בשגיאות בקוד כדי לנהל בעיות פוטנציאליות כמו כשלים ברשת, בעיות בגישה לקבצים או שגיאות ב-API.
מגבלות
- מגבלות גודל הקובץ משתנות בהתאם לשיטה (ראו טבלת השוואה) ולסוג הקובץ.
- נתונים מוטבעים מגדילים את גודל המטען הייעודי (payload) של הבקשה.
- ההעלאות באמצעות File API הן זמניות והתוקף שלהן פג אחרי 48 שעות.
- הגודל המקסימלי של מטען ייעודי (payload) שאפשר לאחזר מכתובת URL חיצונית הוא 100MB, ויש תמיכה בסוגי תוכן ספציפיים.
המאמרים הבאים
- אתם יכולים לנסות לכתוב הנחיות מולטימודאליות משלכם באמצעות Google AI Studio.
- מידע על הכללת קבצים בהנחיות זמין במדריכים בנושא Vision, אודיו ועיבוד מסמכים.