Metodat e hyrjes së skedarëve

Ky udhëzues shpjegon mënyrat e ndryshme se si mund të përfshish skedarë të mediave si imazhe, audio, video dhe dokumente kur bën kërkesa te Gemini API. Metodat e reja mbështeten në të gjitha pikat fundore të Gemini API, duke përfshirë API-në e grupeve, ndërveprimeve dhe transmetimeve të drejtpërdrejta. Zgjedhja e metodës së duhur varet nga madhësia e skedarit, vendi ku ruhen aktualisht të dhënat e tua dhe sa shpesh planifikon ta përdorësh skedarin.

Mënyra më e thjeshtë për të përfshirë një skedar si hyrje është të lexosh një skedar lokal dhe ta përfshish atë në një kërkesë. Shembulli i mëposhtëm tregon se si të lexosh një skedar lokal PDF. Dokumentet PDF janë të kufizuara në 50 MB për këtë metodë. Shiko Tabelën e krahasimit të metodave të hyrjes për një listë të plotë të llojeve dhe kufijve të hyrjes së skedarëve.

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.8-flash",
  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.8-flash",
        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.8-flash: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 metodave të hyrjes

Tabela e mëposhtme krahason çdo metodë hyrjeje me kufijtë e skedarëve dhe rastet më të mira të përdorimit. Ki parasysh 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.

Të dhënat e ndërfutura

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

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

Merr nga një URL

Mund të marrësh gjithashtu një skedar nga një URL, ta konvertosh atë në bajt dhe ta përfshish atë në hyrje.

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.8-flash",
  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.8-flash",
        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.8-flash: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

Gemini File API

File API është krijuar për skedarë më të mëdhenj (deri në 2 GB) ose skedarë që synon t'i përdorësh në disa kërkesa.

Ngarkimi standard i skedarit

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

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.8-flash",
    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.8-flash",
    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.8-flash: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 e tua janë tashmë në Google Cloud Storage, nuk është e nevojshme t'i shkarkosh dhe t'i ngarkosh përsëri. Mund ta regjistrosh drejtpërdrejt me File API.

1. Jep qasje për Agjentin e shërbimit për çdo grupim

   1. Aktivizo Gemini API në projektin tënd të Google Cloud.

   2. Krijo agjentin e shërbimit:

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

   3. Jepi leje Gemini API Service Agent për të lexuar grupet e tua të hapësirës ruajtëse.

      Përdoruesi duhet t'i caktojë Storage Object Viewer rolin e IAM-së këtij agjenti shërbimi në segmentet specifike të hapësirës ruajtëse që synon të përdorë.

   Kjo qasje nuk skadon si parazgjedhje, por mund të ndryshohet në çdo kohë. Mund të përdorësh gjithashtu komandat e SDK-së së IAM-së së Google Cloud Storage për të dhënë leje.

2. Vërteto shërbimin tënd

   Parakushtet

   • Aktivizo API-në
   • Krijo një llogari shërbimi/agjenti me lejet e duhura.

   Në fillim duhet të vërtetosh identitetin si shërbimi që ka lejet e shikuesit të objektit të hapësirës ruajtëse. Mënyra se si ndodh kjo varet nga mjedisi në të cilin do të ekzekutohet kodi yt i menaxhimit të skedarëve.

   Jashtë Google Cloud

   Nëse kodi yt po ekzekutohet nga jashtë Google Cloud, si p.sh. nga desktopi yt, shkarko kredencialet e llogarisë nga "Konsola e Google Cloud" me hapat e mëposhtëm:

   1. Shfleto te Konsola e llogarisë së shërbimit
   2. Zgjidh llogarinë përkatëse të shërbimit
   3. Zgjidh skedën Çelësat dhe zgjidh Shto çelës, Krijo çelës të ri
   4. Zgjidh llojin e çelësit JSON dhe mbaj shënim se ku është shkarkuar skedari në makinën tënde.

   Për më shumë detaje, shiko dokumentacionin zyrtar të Google Cloud për menaxhimin e çelësit të llogarisë së shërbimit.

   Më pas përdor komandat e mëposhtme për t'u identifikuar. Këto komanda supozojnë se skedari i llogarisë sate të shërbimit është në direktorinë aktuale, me emrin 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 ekzekuton drejtpërdrejt në Google Cloud, për shembull duke përdorur funksionet e Cloud Run ose një shembull të Compute Engine, do të kesh kredenciale të nënkuptuara, por do të duhet të riautentikohesh për të dhënë shtrirjet e duhura.

   Python

   Ky kod pret që shërbimi të ekzekutohet në një mjedis ku Kredencialet e parazgjedhura të aplikacionit mund të merren automatikisht, si p.sh. 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ë ekzekutohet në një mjedis ku Kredencialet e parazgjedhura të aplikacionit mund të merren automatikisht, si p.sh. 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

   Kjo është një komandë interaktive. Për shërbime si Compute Engine, mund të bashkëngjitësh fushëveprime te shërbimi që ekzekutohet në nivelin e konfigurimit. Shiko dokumentet e shërbimit të menaxhuar 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"
   

3. Regjistrimi i skedarit (Files API)

   Përdor Files API për të regjistruar skedarët dhe për të prodhuar një shteg të Files API që mund të përdoret drejtpërdrejt në Gemini API.

   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.8-flash",
       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"]}'
   

URL-të e jashtme HTTP / të nënshkruara

Mund të kalosh URL-të HTTPS të qasshme publikisht ose URL-të e nënshkruara paraprakisht (të përputhshme me URL-të e nënshkruara paraprakisht të S3 dhe SAS të Azure) drejtpërdrejt në kërkesën tënde për gjenerim. Gemini API do të marrë përmbajtjet në mënyrë të sigurt gjatë përpunimit. Kjo është ideale për skedarët që nuk dëshiron t'i ngarkosh përsëri. Çdo skedar mund të jetë deri në 15 MB. Për skedarë më të mëdhenj, përdor File API.

Mund të përdorësh URL publike ose me identifikim si hyrje duke përdorur URL-të në fushën file_uri.

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.8-flash",
    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.8-flash',
    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://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash: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"
                  }
                }
              ]
            }
          ]
        }'

Qasshmëria

Verifiko që URL-të që jep nuk të çojnë në faqe që kërkojnë një identifikim ose që janë pas një muri pagese. Për bazat e të dhënave private, sigurohu që të krijosh një URL të nënshkruar me lejet e duhura të qasjes dhe skadimin.

Kontrollet e sigurisë

Sistemi kryen një kontroll të moderimit të përmbajtjes në URL për të konfirmuar që ato plotësojnë standardet e sigurisë dhe të politikave (p.sh. përmbajtje jo të tërhequra dhe me mur pagese). Nëse URL-ja që ke dhënë dështon në këtë kontroll, do të marrësh një url_retrieval_status nga URL_RETRIEVAL_STATUS_UNSAFE.

Llojet e mbështetura të përmbajtjes

Kjo listë e llojeve të mbështetura të skedarëve dhe kufizimeve synohet si udhëzim fillestar dhe nuk është gjithëpërfshirëse. Paketa efektive e llojeve të mbështetura është subjekt i ndryshimit dhe mund të variojë bazuar në modelin specifik dhe versionin e tokenizuesit në përdorim. Llojet e pambështetura do të shkaktojnë një gabim. Përveç kësaj, marrja e përmbajtjes për këto lloje skedarësh aktualisht mbështet vetëm URL-të të qasshme publikisht.

Llojet e skedarëve të tekstit

• text/html
• text/css
• text/plain
• text/xml
• text/csv
• text/rtf
• text/javascript

Llojet e skedarëve të aplikacioneve

• application/json
• application/pdf

Llojet e skedarëve të imazheve

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

Llojet e skedarëve të videove

• video/mp4
• video/mpeg
• video/quicktime
• video/avi
• video/x-flv
• video/mpg
• video/webm
• video/wmv
• video/3gpp

Praktikat më të mira

• Zgjidh metodën e duhur: Përdor të dhënat e integruara për skedarët e vegjël dhe të përkohshëm. Përdor File API për skedarët më të mëdhenj ose të përdorur shpesh. Përdor URL-të e jashtme për të dhënat që janë strehuar tashmë online.
• Specifiko llojet e MIME-s: Jep gjithmonë llojin e saktë të MIME-s për të dhënat e skedarit për të siguruar përpunimin e duhur.
• Menaxho gabimet: Zbato menaxhimin e gabimeve në kodin tënd për të menaxhuar problemet e mundshme si dështimet e rrjetit, problemet e qasjes në skedar ose gabimet e API-së.
• Menaxho lejet e GCS-së: Kur përdor regjistrimin e GCS-së, jepi "Agjentit të shërbimit të Gemini API" vetëm rolin e nevojshëm të Storage Object Viewer në grupet specifike.
• Siguria e URL-ve të nënshkruara: Sigurohu që URL-të e nënshkruara të kenë një kohë të përshtatshme skadimi dhe leje të kufizuara.

Kufizimet

• Kufijtë e madhësisë së skedarit ndryshojnë sipas metodës (shiko tabelën e krahasimit) dhe llojit të skedarit.
• Të dhënat e integruara rritin madhësinë e ngarkesës së kërkesës.
• Ngarkimet e API-së së skedarëve janë të përkohshme dhe skadojnë pas 48 orësh.
• Marrja e URL-ve të jashtme është e kufizuar në 15 MB për skedar dhe mbështet lloje specifike të përmbajtjeve.
• Regjistrimi i Google Cloud Storage kërkon konfigurimin e duhur të IAM-së dhe menaxhimin e token-it të OAuth-së.

Çfarë ka më pas

• Provo të shkruash kërkesat e tua multimodale duke përdorur Google AI Studio.
• Për informacione në lidhje me përfshirjen e skedarëve në kërkesat e tua, shiko udhëzuesit e Vision, Audio dhe Përpunimit të dokumenteve.
• Për më shumë udhëzime për hartimin e kërkesave, si p.sh. rregullimi i parametrave të kampionimit, shiko udhëzuesin e Strategjive të kërkesave.