يوضّح هذا الدليل الطرق المختلفة التي يمكنك من خلالها تضمين ملفات الوسائط، مثل الصور والملفات الصوتية والفيديوهات والمستندات، عند إرسال طلبات إلى Gemini API. تتوفّر الطرق الجديدة في جميع نقاط نهاية Gemini API، بما في ذلك Batch وInteractions وLive API. يعتمد اختيار الطريقة المناسبة على حجم ملفك ومكان تخزين بياناتك ومدى تكرار استخدامك للملف.
أسهل طريقة لتضمين ملف كإدخال هي قراءة ملف محلي وتضمينه في طلب. يوضّح المثال التالي كيفية قراءة ملف PDF محلي. يقتصر حجم ملفات PDF على 50 ميغابايت لهذه الطريقة. راجِع جدول مقارنة طريقة الإدخال للاطّلاع على قائمة كاملة بأنواع إدخال الملفات وحدودها.
Python
from google import genai
import pathlib
import base64
client = genai.Client()
filepath = pathlib.Path('my_local_file.pdf')
prompt = "Summarize this document"
interaction = client.interactions.create(
model="gemini-3.6-flash",
input=[
{"type": "text", "text": prompt},
{"type": "document", "data": base64.b64encode(filepath.read_bytes()).decode('utf-8'), "mime_type": "application/pdf"}
]
)
print(interaction.output_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.6-flash",
input: [
{ type: "text", text: prompt },
{
type: "document",
data: fs.readFileSync(filePath).toString("base64"),
mime_type: "application/pdf"
}
]
});
console.log(interaction.output_text);
}
main();
راحة
# 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.6-flash",
"input": [
{"type": "text", "text": "Summarize this document"},
{
"type": "document",
"data": "'${B64_CONTENT}'",
"mime_type": "application/pdf"
}
]
}'
مقارنة طريقة الإدخال
يقارن الجدول التالي بين كل طريقة إدخال مع حدود الملفات وأفضل حالات الاستخدام. يُرجى العِلم أنّ الحدّ الأقصى المسموح به لحجم الملف قد يختلف حسب نوع الملف والنموذج أو أداة تقسيم الكلمات المستخدَمة لمعالجة الملف.
| الطريقة | الأفضل لـ | الحجم الأقصى للملف | الاستمرارية |
|---|---|---|---|
| البيانات المضمّنة | الاختبار السريع والملفات الصغيرة والتطبيقات في الوقت الفعلي | 100 ميغابايت لكل طلب أو بيانات (50 ميغابايت لملفات PDF) |
بلا (يتم إرسالها مع كل طلب) |
| تحميل الملفات باستخدام File API | الملفات الكبيرة والملفات المستخدَمة عدة مرات | 2 غيغابايت لكل ملف، ما يصل إلى 20 غيغابايت لكل مشروع |
48 ساعة |
| تسجيل عنوان URI لملفات Google Cloud Storage باستخدام File API | الملفات الكبيرة المخزَّنة حاليًا في Google Cloud Storage والملفات المستخدَمة عدة مرات | 2 غيغابايت لكل ملف، بدون حدود إجمالية لمساحة التخزين | بلا (يتم جلبها لكل طلب). يمكن أن يمنح التسجيل لمرة واحدة إمكانية الوصول لمدة تصل إلى 30 يومًا. |
| عناوين URL الخارجية | البيانات العلنية أو البيانات في حِزم السحابة الإلكترونية (AWS أو Azure أو GCS) بدون إعادة تحميلها | 100 ميغابايت لكل طلب/بيانات | بلا (يتم جلبها لكل طلب) |
البيانات المضمّنة
بالنسبة إلى الملفات الأصغر حجمًا (أقل من 100 ميغابايت أو 50 ميغابايت لملفات PDF)، يمكنك تمرير البيانات مباشرةً في بيانات الطلب. هذه هي الطريقة الأسهل لإجراء اختبارات سريعة أو إنشاء تطبيقات تعالج البيانات المؤقتة في الوقت الفعلي. يمكنك تقديم البيانات كسلاسل base64 مشفّرة أو من خلال قراءة الملفات المحلية مباشرةً.
للاطّلاع على مثال على القراءة من ملف محلي، راجِع المثال في بداية هذه الصفحة.
الجلب من عنوان URL
يمكنك أيضًا جلب ملف من عنوان URL وتحويله إلى وحدات بايت وتضمينه في الإدخال.
Python
from google import genai
import httpx
client = genai.