Gemini API reference

Kjo referencë API përshkruan standardet, API-të e transmetimit dhe në kohë reale që mund të përdorni për të bashkëvepruar me modelet Gemini. Mund të përdorni API-të REST në çdo mjedis që mbështet kërkesat HTTP. Referojuni udhëzuesit Quickstart për mënyrën se si të filloni me thirrjen tuaj të parë API. Nëse jeni duke kërkuar për referencat për bibliotekat dhe SDK-të tona specifike për gjuhën, shkoni te lidhja për atë gjuhë në navigimin e majtë nën referencat e SDK-së .

Pikat përfundimtare primare

Gemini API është i organizuar rreth pikave kryesore të mëposhtme përfundimtare:

  • Gjenerimi standard i përmbajtjes ( generateContent ): Një pikë përfundimtare standarde REST që përpunon kërkesën tuaj dhe kthen përgjigjen e plotë të modelit në një paketë të vetme. Kjo është më e mira për detyrat jo-interaktive ku mund të prisni për të gjithë rezultatin.
  • Gjenerimi i përmbajtjes së transmetimit ( streamGenerateContent ): Përdor Ngjarjet e dërguara nga serveri (SSE) për të shtyrë pjesë të përgjigjes tek ju ndërsa ato gjenerohen. Kjo siguron një përvojë më të shpejtë, më ndërvepruese për aplikacione si chatbots.
  • Live API ( BidiGenerateContent ): Një API shtetërore e bazuar në WebSocket për transmetim me dy drejtime, i krijuar për rastet e përdorimit të bisedave në kohë reale.
  • Modaliteti i grupit ( batchGenerateContent ): Një pikë përfundimtare standarde REST për dërgimin e grupeve të kërkesave generateContent .
  • Embeddings ( embedContent ): Një pikë përfundimtare standarde REST që gjeneron një vektor të ngulitjes së tekstit nga Content hyrëse.
  • Gen Media API: Pikat përfundimtare për gjenerimin e mediave me modelet tona të specializuara si Imagen për gjenerimin e imazheve dhe Veo për gjenerimin e videove . Binjakët gjithashtu i ka këto aftësi të ndërtuara në të cilat mund të përdorni duke përdorur API- generateContent .
  • API-të e platformës: Pikat përfundimtare të shërbimeve që mbështesin aftësitë kryesore, si ngarkimi i skedarëve dhe numërimi i argumenteve .

Autentifikimi

Të gjitha kërkesat për Gemini API duhet të përfshijnë një kokë x-goog-api-key me çelësin tuaj API. Krijo një të tillë me disa klikime në Google AI Studio .

Më poshtë është një shembull i kërkesës me çelësin API të përfshirë në kokë:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Për udhëzime se si t'ia kaloni çelësin API-së duke përdorur Gemini SDK-të, shihni udhëzuesin Përdorimi i çelësave të Gemini API .

gjenerimi i përmbajtjes

Kjo është pika përfundimtare qendrore për dërgimin e kërkesave te modeli. Ekzistojnë dy pika përfundimtare për gjenerimin e përmbajtjes, ndryshimi kryesor është se si e merrni përgjigjen:

  • generateContent (REST) : Merr një kërkesë dhe jep një përgjigje të vetme pasi modeli të ketë përfunduar të gjithë gjenerimin e tij.
  • streamGenerateContent (SSE) : Merr saktësisht të njëjtën kërkesë, por modeli transmeton pjesë të përgjigjes ndërsa ato gjenerohen. Kjo siguron një përvojë më të mirë të përdoruesit për aplikacionet ndërvepruese pasi ju lejon të shfaqni rezultatet e pjesshme menjëherë.

Kërkoni strukturën e trupit

Trupi i kërkesës është një objekt JSON që është identik si për modalitetin standard ashtu edhe për atë të transmetimit dhe është ndërtuar nga disa objekte thelbësore:

  • Objekti Content : Përfaqëson një kthesë të vetme në një bisedë.
  • Objekti Part : Një pjesë e të dhënave brenda një kthese Content (si teksti ose imazhi).
  • inline_data ( Blob ): Një kontejner për bajt të mediave të papërpunuara dhe llojin e tyre MIME.

Në nivelin më të lartë, trupi i kërkesës përmban një objekt contents , i cili është një listë e objekteve Content , ku secili përfaqëson kthesat në bisedë. Në shumicën e rasteve, për gjenerimin e tekstit bazë, do të keni një objekt të vetëm Content , por nëse dëshironi të ruani historinë e bisedave, mund të përdorni objekte të shumta Content .

Më poshtë tregon një trup tipik të kërkesës generateContent :

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

Struktura e trupit të përgjigjes

Trupi i përgjigjes është i ngjashëm si për modalitetin e transmetimit ashtu edhe për atë standard, përveç për sa vijon:

Në një nivel të lartë, trupi i përgjigjes përmban një objekt candidates , i cili është një listë e objekteve Candidate . Objekti Candidate përmban një objekt Content që ka përgjigjen e gjeneruar të kthyer nga modeli.

Kërkoni shembuj

Shembujt e mëposhtëm tregojnë se si këto komponentë bashkohen për lloje të ndryshme kërkesash.

Prompt vetëm me tekst

Një kërkesë e thjeshtë teksti përbëhet nga një grup contents me një objekt të vetëm Content . Vargu i parts të atij objekti, nga ana tjetër, përmban një objekt të vetëm Part me një fushë text .

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

Prompt multimodal (tekst dhe imazh)

Për të siguruar tekstin dhe imazhin në një prompt, grupi i parts duhet të përmbajë dy objekte Part : një për tekstin dhe një për imazhin inline_data .

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

Biseda me shumë kthesa (chat)

Për të ndërtuar një bisedë me kthesa të shumta, ju përcaktoni grupin e contents me objekte të shumta Content . API do të përdorë të gjithë këtë histori si kontekst për përgjigjen e radhës. role për çdo objekt Content duhet të alternojë ndërmjet user dhe model .

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

Marrëdhëniet kryesore

  • Content është zarfi: Është kontejneri i nivelit të lartë për një kthesë mesazhi, qoftë nga përdoruesi apo nga modeli.
  • Part mundëson multimodalitetin: Përdorni objekte të shumta Part brenda një objekti të vetëm Content për të kombinuar lloje të ndryshme të dhënash (tekst, imazh, video URI, etj.).
  • Zgjidhni metodën tuaj të të dhënave:
    • Për media të vogla, të ngulitura drejtpërdrejt (si shumica e imazheve), përdorni një Part me inline_data .
    • Për skedarët ose skedarët më të mëdhenj që dëshironi të ripërdorni në të gjitha kërkesat, përdorni API-në e skedarit për të ngarkuar skedarin dhe për t'i referuar me një pjesë file_data .
  • Menaxho historikun e bisedave: Për aplikacionet e bisedës duke përdorur API-në REST, ndërto grupin e contents duke shtuar objekte Content për çdo kthesë, duke alternuar midis roleve "user" dhe "model" . Nëse jeni duke përdorur një SDK, referojuni dokumentacionit SDK për mënyrën e rekomanduar për të menaxhuar historikun e bisedave.

Shembuj përgjigjesh

Shembujt e mëposhtëm tregojnë se si këto komponentë bashkohen për lloje të ndryshme kërkesash.

Përgjigje vetëm me tekst

Një përgjigje e thjeshtë teksti përbëhet nga një grup candidates me një ose më shumë objekte content që përmbajnë përgjigjen e modelit.

Më poshtë është një shembull i një përgjigje standarde :

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

Më poshtë është seria e përgjigjeve të transmetimit . Çdo përgjigje përmban një responseId që lidh përgjigjen e plotë së bashku:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets API

Live API ofron një API shtetërore të bazuar në WebSocket për transmetim me dy drejtime për të mundësuar rastet e përdorimit të transmetimit në kohë reale. Mund të rishikoni udhëzuesin Live API dhe referencën Live API për më shumë detaje.

Modele të specializuara

Përveç familjes së modeleve Gemini, Gemini API ofron pika përfundimtare për modele të specializuara si Imagen , Lyria dhe modele të ngulitjes . Ju mund t'i shikoni këto udhëzues nën seksionin Modele.

API-të e platformës

Pjesa tjetër e pikave fundore mundësojnë aftësi shtesë për t'u përdorur me pikat përfundimtare kryesore të përshkruara deri më tani. Shikoni temat "Modaliteti i grupit" dhe API i skedarit në seksionin "Udhëzuesit" për të mësuar më shumë.

Çfarë është më pas

Nëse sapo po filloni, shikoni udhëzuesit e mëposhtëm, të cilët do t'ju ndihmojnë të kuptoni modelin e programimit të Gemini API:

Ju gjithashtu mund të dëshironi të shikoni udhëzuesit e aftësive, të cilat prezantojnë veçori të ndryshme të Gemini API dhe ofrojnë shembuj kodesh: