Kjo faqe është përkthyer nga Cloud Translation API.

Metodat e futjes së skedarëve

Ky udhëzues shpjegon mënyrat e ndryshme se si mund të përfshini skedarë mediatikë si imazhe, audio, video dhe dokumente kur bëni kërkesa te Gemini API. Zgjedhja e metodës së duhur varet nga madhësia e skedarit tuaj, vendi ku ruhen aktualisht të dhënat tuaja dhe sa shpesh planifikoni ta përdorni skedarin.

Mënyra më e thjeshtë për të përfshirë një skedar si të dhënë hyrëse është të lexoni një skedar lokal dhe ta përfshini atë në një njoftim. Shembulli i mëposhtëm tregon se si të lexoni një skedar lokal PDF. PDF-të janë të kufizuara në 50MB për këtë metodë. Shihni tabelën krahasuese të metodës së hyrjes për një listë të plotë të llojeve dhe kufizimeve të hyrjes së skedarëve.

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

PUSHTIM

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

Krahasimi i metodës së hyrjes

Tabela e mëposhtme krahason secilën metodë të futjes me kufizimet e skedarëve dhe rastet më të mira të përdorimit. Vini re se kufiri i madhësisë së skedarit mund të ndryshojë në varësi të llojit të skedarit dhe modelit/tokenizuesit të përdorur për të përpunuar skedarin.

Metoda	Më e mira për	Madhësia maksimale e skedarit	Këmbëngulje
Të dhëna të integruara	Testim i shpejtë, skedarë të vegjël, aplikacione në kohë reale.	100 MB për kërkesë/ngarkesë ( 50 MB për PDF-të )	Asnjë (dërgohet me çdo kërkesë)
Ngarkimi i API-t të skedarëve	Skedarë të mëdhenj, skedarë të përdorur shumë herë.	2 GB për skedar, deri në 20 GB për projekt	48 Orë
Regjistrimi i URI-t GCS të API-t të skedarit	Skedarë të mëdhenj tashmë në Google Cloud Storage, skedarë të përdorur shumë herë.	2 GB për skedar, pa kufizime të përgjithshme të ruajtjes	Asnjë (merret sipas kërkesës). Regjistrimi i vetëm mund të japë akses deri në 30 ditë.
URL-të e jashtme	Të dhëna publike ose të dhëna në "cloud buckets" (AWS, Azure, GCS) pa i ringarkuar.	100 MB për kërkesë/ngarkesë	Asnjë (e marrë sipas kërkesës)

Të dhëna të integruara

Për skedarë më të vegjël (nën 100MB ose 50MB për PDF), mund t'i kaloni të dhënat direkt në ngarkesën e kërkesës. Kjo është metoda më e thjeshtë për teste të shpejta ose aplikacione që trajtojnë të dhëna kalimtare në kohë reale. Mund të ofroni të dhëna si vargje të koduara me base64 ose duke lexuar skedarë lokalë direkt.

Për një shembull të leximit nga një skedar lokal, shihni shembullin në fillim të kësaj faqeje.

Merrni nga një URL

Gjithashtu mund të merrni një skedar nga një URL, ta konvertoni atë në bajt dhe ta përfshini atë në të dhënat hyrëse.

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

PUSHTIM

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-ja e Skedarëve Gemini

API-ja e Skedarëve është projektuar për skedarë më të mëdhenj (deri në 2 GB) ose skedarë që keni ndërmend të përdorni në kërkesa të shumëfishta.

Ngarkimi standard i skedarit

Ngarko një skedar lokal në Gemini API. Skedarët e ngarkuar në këtë mënyrë ruhen përkohësisht (48 orë) dhe përpunohen për rikuperim efikas nga modeli.

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

PUSHTIM

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

Regjistro skedarët e Google Cloud Storage

Nëse të dhënat tuaja janë tashmë në Google Cloud Storage, nuk keni nevojë t'i shkarkoni dhe t'i ringarkoni ato. Mund t'i regjistroni direkt me File API.

Jepni Agjentit të Shërbimit qasje në secilën kovë
1. Aktivizoni Gemini API në projektin tuaj Google Cloud.
2. Krijoni Agjentin e Shërbimit:
  gcloud beta services identity create --service=generativelanguage.googleapis.com --project=<your_project>
3. Jepini leje Agjentit të Shërbimit Gemini API për të lexuar kovat tuaja të ruajtjes.
  Përdoruesi duhet t'i caktojë rolin IAM Storage Object Viewer këtij agjenti shërbimi në kutitë specifike të ruajtjes që synon të përdorë.
Ky akses nuk skadon si parazgjedhje, por mund të ndryshohet në çdo kohë. Gjithashtu mund të përdorni komandat IAM SDK të Google Cloud Storage për të dhënë leje.
Autentifikoni shërbimin tuaj
Parakushte
- Aktivizo API-në
- Krijo një llogari shërbimi/agjent me lejet e duhura.
Së pari duhet të autentifikoheni si shërbimi që ka leje shikuesi të objekteve të ruajtjes. Se si ndodh kjo varet nga mjedisi në të cilin do të ekzekutohet kodi juaj i menaxhimit të skedarëve.
Jashtë Google Cloud
Nëse kodi juaj po ekzekutohet nga jashtë Google Cloud, siç është desktopi juaj, shkarkoni kredencialet e llogarisë nga Google Cloud Console duke ndjekur hapat e mëposhtëm:
1. Shfletoni te konsola e Llogarisë së Shërbimit
2. Zgjidhni llogarinë përkatëse të shërbimit
3. Zgjidhni skedën Çelësa dhe zgjidhni Shto çelës, Krijo çelës të ri
4. Zgjidhni llojin e çelësit JSON dhe shënoni se ku është shkarkuar skedari në makinën tuaj.
Për më shumë detaje, shihni dokumentacionin zyrtar të Google Cloud mbi menaxhimin e çelësave të llogarisë së shërbimit .
Pastaj përdorni komandat e mëposhtme për të autentifikuar. Këto komanda supozojnë se skedari i llogarisë së shërbimit tuaj është në direktorinë aktuale, të quajtur 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'
```
Në Google Cloud
Nëse po ekzekutoni direkt në Google Cloud, për shembull duke përdorur funksionet Cloud Run ose një instancë Compute Engine , do të keni kredenciale të nënkuptuara, por do t'ju duhet të riautentifikoheni për të dhënë fushat e duhura.
Python
Ky kod pret që shërbimi të funksionojë në një mjedis ku Kredencialet Parazgjedhëse të Aplikacionit mund të merren automatikisht, siç janë Cloud Run ose 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
Ky kod pret që shërbimi të funksionojë në një mjedis ku Kredencialet Parazgjedhëse të Aplikacionit mund të merren automatikisht, siç janë Cloud Run ose 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
Ky është një komandë interaktive. Për shërbime si Compute Engine, mund t'i bashkëngjitni fusha veprimi shërbimit që është në ekzekutim në nivelin e konfigurimit. Shihni dokumentet e shërbimit të menaxhuara nga përdoruesi për një shembull.
```
gcloud auth application-default login \
--scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only"
```

Regjistrimi i skedarëve (API i skedarëve)

Përdorni API-n e Files për të regjistruar skedarë dhe për të krijuar një shteg të API-t të Files që mund të përdoret direkt në API-n Gemini.

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

HTTP të jashtëm / URL të nënshkruara

Mund të kaloni URL-të HTTPS të aksesueshme publikisht ose URL-të e para-nënshkruara (të pajtueshme me URL-të e para-nënshkruara S3 dhe Azure SAS) direkt në kërkesën tuaj të gjenerimit. API-ja Gemini do ta marrë përmbajtjen në mënyrë të sigurt gjatë përpunimit. Kjo është ideale për skedarët deri në 100MB që nuk dëshironi t'i ringarkoni.

Mund të përdorni URL publike ose të nënshkruara si të dhëna hyrëse duke përdorur URL-të në fushën 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();

PUSHTIM

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

Aksesueshmëria

Verifikoni që URL-të që jepni nuk çojnë në faqe që kërkojnë hyrje ose që ndodhen pas një muri pagese. Për bazat e të dhënave private, sigurohuni që të krijoni një URL të nënshkruar me lejet e sakta të aksesit dhe afatin e skadimit.

Kontrollet e sigurisë

Sistemi kryen një kontroll të moderimit të përmbajtjes në URL për të konfirmuar se ato përmbushin standardet e sigurisë dhe të politikave (p.sh. përmbajtje pa zgjedhje dhe me pagesë). Nëse URL-ja që keni dhënë nuk e kalon këtë kontroll, do të merrni një url_retrieval_status URL_RETRIEVAL_STATUS_UNSAFE .

Llojet e përmbajtjes së mbështetur

Kjo listë e llojeve të skedarëve të mbështetur dhe kufizimeve është menduar si udhëzim fillestar dhe nuk është gjithëpërfshirëse. Seti efektiv i llojeve të mbështetura mund të ndryshojë dhe mund të ndryshojë në bazë të modelit specifik dhe versionit të tokenizuesit në përdorim. Llojet e pambështetura do të rezultojnë në një gabim. Përveç kësaj, rikthimi i përmbajtjes për këto lloje skedarësh aktualisht mbështet vetëm URL-të e aksesueshme publikisht.

Llojet e skedarëve të tekstit

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

Llojet e skedarëve të aplikacionit

application/json
application/pdf

Llojet e skedarëve të imazheve

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

Praktikat më të mira

Zgjidhni metodën e duhur: Përdorni të dhëna të integruara për skedarë të vegjël dhe të përkohshëm. Përdorni API-n e Skedarëve për skedarë më të mëdhenj ose që përdoren shpesh. Përdorni URL-të e jashtme për të dhënat që tashmë janë të vendosura në internet.
Specifikoni Llojet MIME: Jepni gjithmonë llojin e saktë MIME për të dhënat e skedarit për të siguruar përpunimin e duhur.
Trajtimi i Gabimeve: Implementoni trajtimin e gabimeve në kodin tuaj për të menaxhuar probleme të mundshme si dështimet e rrjetit, problemet e aksesit në skedarë ose gabimet e API-t.
Menaxho Lejet e GCS: Kur përdorni regjistrimin e GCS, jepini Agjentit të Shërbimit Gemini API vetëm rolin e nevojshëm të Storage Object Viewer në kovat specifike.
Siguria e URL-ve të nënshkruara: Sigurohuni që URL-të e nënshkruara të kenë një kohë skadimi të përshtatshme dhe leje të kufizuara.

Kufizime

Limitet e madhësisë së skedarit ndryshojnë në varësi të metodës (shih tabelën krahasuese ) dhe llojit të skedarit.
Të dhënat në linjë rrisin madhësinë e ngarkesës së kërkesës.
Ngarkimet e API-t të skedarëve janë të përkohshme dhe skadojnë pas 48 orësh.
Marrja e URL-ve të jashtme është e kufizuar në 100MB për ngarkesë dhe mbështet lloje specifike përmbajtjeje.
Regjistrimi në Google Cloud Storage kërkon konfigurimin e duhur të IAM dhe menaxhimin e tokenëve OAuth.

Çfarë vjen më pas

Provo të shkruash vetë kërkesat multimodale duke përdorur Google AI Studio .
Për informacion mbi përfshirjen e skedarëve në kërkesat tuaja, shihni udhëzuesit e përpunimit të Vizionit , Audios dhe Dokumentit .
Për më shumë udhëzime mbi dizajnin e shpejtë, si akordimi i parametrave të marrjes së mostrave, shihni udhëzuesin e strategjive të shpejtë .