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

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

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

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)

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

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

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

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

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

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

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

دریافت از یک URL

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

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)

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

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

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 a prompt
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[prompt, audio_file]
)
print(response.text)

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

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

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

اگر داده‌های شما از قبل در فضای ذخیره‌سازی ابری گوگل وجود دارد، نیازی به دانلود و آپلود مجدد آنها ندارید. می‌توانید آنها را مستقیماً با 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
   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)
   

   رابط خط فرمان

   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 با دسترسی عمومی یا آدرس‌های اینترنتی از پیش امضا شده (سازگار با آدرس‌های اینترنتی امضا شده S3 و Azure SAS) را مستقیماً در درخواست تولید خود ارسال کنید. رابط برنامه‌نویسی نرم‌افزار Gemini محتوا را به طور ایمن در حین پردازش دریافت می‌کند. این برای فایل‌هایی تا حجم ۱۰۰ مگابایت که نمی‌خواهید دوباره آپلود کنید، ایده‌آل است.

شما می‌توانید با استفاده از URL های موجود در فیلد file_uri از URL های عمومی یا امضا شده به عنوان ورودی استفاده کنید.

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)

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

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

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

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

محدودیت‌ها

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

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

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