Gemini API reference

Kjo referencë API përshkruan API-të standarde, të transmetimit dhe në kohë reale që mund të përdorni për të bashkëvepruar me modelet Gemini. Ju mund të përdorni API-të REST në çdo mjedis që mbështet kërkesat HTTP. Referojuni udhëzuesit të Fillimit të Shpejtë për mënyrën se si të filloni me thirrjen tuaj të parë të API-t. Nëse po kërkoni referenca 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 kryesore të fundit

API-ja Gemini është e organizuar rreth pikave kryesore të mëposhtme:

  • Gjenerimi standard i përmbajtjes ( generateContent ): Një pikë fundore 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 rezultatin e plotë.
  • Gjenerimi i përmbajtjes së transmetimit ( streamGenerateContent ): Përdor Ngjarjet e Dërguara nga Serveri (SSE) për t'ju dërguar pjesë të përgjigjes ndërsa ato gjenerohen. Kjo ofron një përvojë më të shpejtë dhe më interaktive për aplikacione si chatbot-et.
  • Live API ( BidiGenerateContent ): Një API me gjendje statementale e bazuar në WebSocket për transmetim dypalësh, i projektuar për raste përdorimi bisedor në kohë reale.
  • Modaliteti i serisë ( batchGenerateContent ): Një pikë fundore standarde REST për dërgimin e serive të kërkesave generateContent .
  • Embeddings ( embedContent ): Një pikë fundore standarde REST që gjeneron një vektor të ngulitjes së tekstit nga Content hyrëse.
  • API-të e Gen Media: Pikat fundore për gjenerimin e medias me modelet tona të specializuara si Imagen për gjenerimin e imazheve dhe Veo për gjenerimin e videove . Gemini gjithashtu ka këto aftësi të integruara, të cilat mund t'i qaseni duke përdorur API-në generateContent .
  • API-të e platformës: Pikat fundore të shërbimeve që mbështesin aftësitë kryesore siç janë ngarkimi i skedarëve dhe numërimi i tokenëve .

Autentifikimi

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

Më poshtë është një shembull kërkese 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 ta kaloni çelësin tuaj te API duke përdorur SDK-të Gemini, shihni udhëzuesin Përdorimi i çelësave Gemini API .

Gjenerimi i përmbajtjes

Kjo është pika qendrore për dërgimin e kërkesave në model. Ekzistojnë dy pika përfundimtare për gjenerimin e përmbajtjes, ndryshimi kryesor është mënyra 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 ofron një përvojë më të mirë përdoruesi për aplikacionet interaktive pasi ju lejon të shfaqni menjëherë rezultate të pjesshme.

Kërko strukturën e trupit

Trupi i kërkesës është një objekt JSON që është identik si për modalitetet standarde ashtu edhe për ato 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 një imazh).
  • inline_data ( Blob ): Një kontejner për bajtet e medias së papërpunuar 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ë objektesh Content , secili prej të cilëve përfaqëson raundet në bisedë. Në shumicën e rasteve, për gjenerimin bazë të tekstit, do të keni një objekt të vetëm Content , por nëse dëshironi të ruani historikun e bisedës, mund të përdorni objekte të shumta Content .

Më poshtë tregohet një trup tipik kërkese 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ë reagimit

Trupi i përgjigjes është i ngjashëm si për modalitetin e transmetimit ashtu edhe për atë standard, përveç 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.

Njoftim vetëm me tekst

Një komandë e thjeshtë teksti përbëhet nga një varg 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."
          }
        ]
      }
    ]
  }'

Njoftim multimodal (tekst dhe imazh)

Për të ofruar si tekst ashtu edhe një imazh në një kërkesë, vargu 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ë shumëfishta, ju përcaktoni vargun e contents me objekte të shumëfishta Content . API do ta përdorë të gjithë këtë histori si kontekst për përgjigjen tjetër. role për secilin objekt Content duhet të alternojë midis 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." }
        ]
      }
    ]
  }'

Përmbledhje 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ë shumëfishta Part brenda një objekti të vetëm Content për të kombinuar lloje të ndryshme të të dhënave (tekst, imazh, URI videoje, 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ë më të mëdhenj ose skedarë që dëshironi të ripërdorni në të gjitha kërkesat, përdorni File API për të ngarkuar skedarin dhe për ta referuar atë me një pjesë file_data .
  • Menaxho historikun e bisedave: Për aplikacionet e bisedave që përdorin REST API, ndërtoni vargun e contents duke shtuar objekte Content për çdo raund, duke alternuar midis roleve "user" dhe "model" . Nëse po përdorni një SDK, referojuni dokumentacionit të SDK-së 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ë tekstuale përbëhet nga një varg candidates me një ose më shumë objekte content që përmbajnë përgjigjen e modelit.

Më poshtë është një shembull i një përgjigjeje 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ë një seri përgjigjesh të transmetuara . Ç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"
}

API Live (BidiGenerateContent) API WebSockets

Live API ofron një API të bazuar në WebSocket me gjendje të plotë për transmetim dypalësh për të mundësuar rastet e përdorimit të transmetimit në kohë reale. Mund të rishikoni udhëzuesin e Live API dhe referencën e Live API për më shumë detaje.

Modele të specializuara

Përveç familjes së modeleve Gemini, Gemini API ofron pika fundore për modele të specializuara si Imagen , Lyria dhe modele integruese . Mund t'i shikoni këto udhëzues në seksionin Modelet.

API-të e platformës

Pjesa tjetër e pikave fundore mundëson funksione shtesë për t'u përdorur me pikat fundore kryesore të përshkruara deri më tani. Shikoni temat Modaliteti i grupeve dhe API-ja e skedarëve në seksionin Udhëzues për të mësuar më shumë.

Çfarë vjen më pas

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

Gjithashtu, mund të dëshironi të shikoni udhëzuesit e aftësive, të cilët prezantojnë veçori të ndryshme të Gemini API dhe ofrojnë shembuj kodi: