روش‌های ورودی فایل

این راهنما روش‌های مختلفی را که می‌توانید هنگام درخواست به API Gemini فایل‌های رسانه‌ای مانند تصاویر، صدا، ویدیو و اسناد را وارد کنید، توضیح می‌دهد. روش‌های جدید در تمام نقاط پایانی API Gemini، از جمله Batch، Interactions و Live API، پشتیبانی می‌شوند. انتخاب روش مناسب به اندازه فایل شما، محل ذخیره داده‌های شما و تعداد دفعاتی که قصد استفاده از فایل را دارید، بستگی دارد.

ساده‌ترین راه برای گنجاندن یک فایل به عنوان ورودی، خواندن یک فایل محلی و گنجاندن آن در یک اعلان است. مثال زیر نحوه خواندن یک فایل PDF محلی را نشان می‌دهد. فایل‌های PDF برای این روش به 50 مگابایت محدود هستند. برای لیست کاملی از انواع و محدودیت‌های ورودی فایل، به جدول مقایسه روش‌های ورودی مراجعه کنید.

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)

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();

# 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"
      }
    ]
  }'

مقایسه روش ورودی

جدول زیر هر روش ورودی را با محدودیت‌های فایل و بهترین موارد استفاده مقایسه می‌کند. توجه داشته باشید که محدودیت اندازه فایل ممکن است بسته به نوع فایل و مدل یا توکنایزر مورد استفاده برای پردازش فایل متفاوت باشد.

داده‌های درون‌خطی

برای فایل‌های کوچک‌تر (زیر ۱۰۰ مگابایت یا ۵۰ مگابایت برای فایل‌های PDF)، می‌توانید داده‌ها را مستقیماً در payload درخواست ارسال کنید. این ساده‌ترین روش برای تست‌های سریع یا برنامه‌هایی است که داده‌های گذرا و بلادرنگ را مدیریت می‌کنند. می‌توانید داده‌ها را به صورت رشته‌های کدگذاری شده base64 یا با خواندن مستقیم فایل‌های محلی ارائه دهید.

برای مثالی از خواندن از یک فایل محلی، به مثال ابتدای این صفحه مراجعه کنید.

دریافت از یک URL

همچنین می‌توانید یک فایل را از یک URL دریافت کنید، آن را به بایت تبدیل کنید و در ورودی قرار دهید.

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)

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();

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

API فایل Gemini

API فایل برای فایل‌های بزرگتر (تا ۲ گیگابایت) یا فایل‌هایی که قصد استفاده از آنها را در چندین درخواست دارید، طراحی شده است.

آپلود فایل استاندارد

یک فایل محلی را در رابط برنامه‌نویسی نرم‌افزار Gemini بارگذاری کنید. فایل‌های بارگذاری‌شده به این روش به‌طور موقت (۴۸ ساعت) ذخیره می‌شوند و برای بازیابی کارآمد توسط مدل پردازش می‌شوند.

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)

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();

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}'"}
      ]
    }'

ثبت فایل‌های ذخیره‌سازی ابری گوگل

اگر داده‌های شما از قبل در فضای ذخیره‌سازی ابری گوگل وجود دارد، نیازی به دانلود و آپلود مجدد آنها ندارید. می‌توانید آنها را مستقیماً با File API ثبت کنید.

1. به نماینده خدمات (Service Agent) دسترسی به هر سطل (Bucket) را اعطا کنید.

   1. رابط برنامه‌نویسی Gemini را در پروژه Google Cloud خود فعال کنید.

   2. ایجاد عامل سرویس:

      gcloud beta services identity create --service=generativelanguage.googleapis.com --project=<your_project>

   3. به نماینده سرویس API Gemini مجوزهای لازم برای خواندن مخازن ذخیره‌سازی خود را اعطا کنید .

      کاربر باید نقش IAM مربوط به Storage Object Viewer به این عامل سرویس در سطل‌های ذخیره‌سازی خاصی که قصد استفاده از آنها را دارد، اختصاص دهد.

   این دسترسی به طور پیش‌فرض منقضی نمی‌شود، اما می‌توان آن را در هر زمانی تغییر داد. همچنین می‌توانید از دستورات Google Cloud Storage IAM SDK برای اعطای مجوزها استفاده کنید.

2. خدمات خود را تأیید کنید

   پیش‌نیازها

   • فعال کردن API
   • یک حساب کاربری یا عامل سرویس با مجوزهای مناسب ایجاد کنید.

   ابتدا باید به عنوان سرویسی که مجوزهای مشاهده اشیاء ذخیره‌سازی را دارد، احراز هویت شوید. نحوه انجام این کار بستگی به محیطی دارد که کد مدیریت فایل شما در آن اجرا خواهد شد.

   خارج از فضای ابری گوگل

   اگر کد شما از خارج از Google Cloud، مانند دسکتاپ شما، اجرا می‌شود، اعتبارنامه‌های حساب را از Google Cloud Console با مراحل زیر دانلود کنید:

   1. به کنسول حساب سرویس بروید
   2. حساب سرویس مربوطه را انتخاب کنید
   3. برگه کلیدها را انتخاب کنید و افزودن کلید، ایجاد کلید جدید را انتخاب کنید.
   4. نوع کلید JSON را انتخاب کنید و توجه داشته باشید که فایل در کجای دستگاه شما دانلود شده است.

   برای جزئیات بیشتر، به مستندات رسمی Google Cloud در مورد مدیریت کلید حساب سرویس مراجعه کنید.

   سپس از دستورات زیر برای احراز هویت استفاده کنید. این دستورات فرض می‌کنند که فایل حساب سرویس شما در دایرکتوری فعلی با نام service-account.json قرار دارد.

   پایتون

   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
   )
   

   جاوا اسکریپت

   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
   });
   

   رابط خط فرمان

   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 اجرا می‌کنید، مثلاً با استفاده از توابع Cloud Run یا یک نمونه Compute Engine ، اعتبارنامه‌های ضمنی خواهید داشت اما برای اعطای دامنه‌های مناسب، باید دوباره احراز هویت کنید.

   پایتون

   این کد انتظار دارد که سرویس در محیطی اجرا شود که بتوان اعتبارنامه‌های پیش‌فرض برنامه (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)
   

   جاوا اسکریپت

   این کد انتظار دارد که سرویس در محیطی اجرا شود که بتوان اعتبارنامه‌های پیش‌فرض برنامه (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'
     ]
   });
   

   رابط خط فرمان

   این یک دستور تعاملی است. برای سرویس‌هایی مانند Compute Engine می‌توانید در سطح پیکربندی، محدوده‌ها را به سرویس در حال اجرا متصل کنید. برای مثال ، به اسناد سرویس مدیریت‌شده توسط کاربر مراجعه کنید.

   gcloud auth application-default login \
   --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only"
   

3. ثبت فایل (API فایل‌ها)

   از API فایل‌ها برای ثبت فایل‌ها و ایجاد یک مسیر API فایل‌ها که مستقیماً در API جمینی قابل استفاده باشد، استفاده کنید.

   پایتون

   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)
   

   جاوا اسکریپت

   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();
   

   رابط خط فرمان

   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"]}'
   

HTTP خارجی / URL های امضا شده

شما می‌توانید آدرس‌های اینترنتی HTTPS که برای عموم قابل دسترسی هستند یا آدرس‌های اینترنتی از پیش امضا شده را مستقیماً در درخواست خود ارسال کنید. رابط برنامه‌نویسی نرم‌افزار Gemini محتوا را در حین پردازش به صورت ایمن دریافت می‌کند. این برای فایل‌هایی تا حجم ۱۰۰ مگابایت که نمی‌خواهید دوباره آپلود کنید، ایده‌آل است.

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)

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();

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های قابل دسترس عمومی پشتیبانی می‌کند.

بهترین شیوه‌ها

• روش مناسب را انتخاب کنید: برای فایل‌های کوچک و گذرا از داده‌های درون‌خطی استفاده کنید. برای فایل‌های بزرگ‌تر یا پرکاربرد از API فایل استفاده کنید. برای داده‌هایی که از قبل به صورت آنلاین میزبانی می‌شوند، از URLهای خارجی استفاده کنید.
• انواع MIME را مشخص کنید: همیشه نوع MIME صحیح را برای داده‌های فایل ارائه دهید تا پردازش صحیح تضمین شود.
• مدیریت خطاها: مدیریت خطا را در کد خود پیاده‌سازی کنید تا مشکلات احتمالی مانند خرابی شبکه، مشکلات دسترسی به فایل یا خطاهای API را مدیریت کنید.

محدودیت‌ها

• محدودیت‌های اندازه فایل بسته به روش (به جدول مقایسه مراجعه کنید) و نوع فایل متفاوت است.
• داده‌های درون‌خطی، حجم بار درخواست را افزایش می‌دهند.
• آپلودهای API فایل موقتی هستند و پس از ۴۸ ساعت منقضی می‌شوند.
• دریافت URL خارجی به ۱۰۰ مگابایت در هر بار داده محدود شده است و از انواع محتوای خاص پشتیبانی می‌کند.

قدم بعدی چیست؟

• سعی کنید با استفاده از Google AI Studio، دستورالعمل‌های چندوجهی خودتان را بنویسید.
• برای اطلاعات مربوط به گنجاندن فایل‌ها در اعلان‌هایتان، به راهنماهای پردازش تصویر ، صدا و سند مراجعه کنید.