Gemini API reference

Questo riferimento API descrive le API standard, di streaming e in tempo reale che puoi utilizzare per interagire con i modelli Gemini. Puoi utilizzare le API REST in qualsiasi ambiente che supporta le richieste HTTP. Consulta la guida rapida per scoprire come iniziare a utilizzare la tua prima chiamata API. Se stai cercando i riferimenti per le nostre librerie e SDK specifici per la lingua, vai al link per la lingua nella navigazione a sinistra in Riferimenti SDK.

Endpoint principali

L'API Gemini è organizzata intorno ai seguenti endpoint principali:

  • Generazione di contenuti standard (generateContent): Un endpoint REST standard che elabora la richiesta e restituisce la risposta completa del modello in un unico pacchetto. Questa opzione è ideale per attività non interattive in cui puoi attendere l'intero risultato.
  • Generazione di contenuti di streaming (streamGenerateContent): utilizza gli eventi inviati dal server (SSE) per inviarti i blocchi della risposta man mano che vengono generati. Ciò offre un'esperienza più rapida e interattiva per applicazioni come i chatbot.
  • API Live (BidiGenerateContent): un'API stateful basata su WebSocket per lo streaming bidirezionale, progettata per casi d'uso conversazionali in tempo reale.
  • Modalità batch (batchGenerateContent): un endpoint REST standard per l'invio di batch di richieste generateContent.
  • Embedding (embedContent): un endpoint REST standard che genera un vettore di embedding di testo dall'input Content.
  • API Gen Media:endpoint per la generazione di contenuti multimediali con i nostri modelli specializzati, come Imagen per la generazione di immagini e Veo per la generazione di video. Gemini dispone anche di queste funzionalità integrate, a cui puoi accedere utilizzando l'API generateContent.
  • API della piattaforma:endpoint di utilità che supportano funzionalità di base come il caricamento di file e il conteggio dei token.

Autenticazione

Tutte le richieste all'API Gemini devono includere un'intestazione x-goog-api-key con la tua chiave API. Creane una con pochi clic in Google AI Studio.

Di seguito è riportato un esempio di richiesta con la chiave API inclusa nell'intestazione:

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

Per istruzioni su come trasmettere la chiave all'API utilizzando gli SDK Gemini, consulta la guida Utilizzo delle chiavi API Gemini.

Generazione di contenuti

Questo è l'endpoint centrale per l'invio di prompt al modello. Esistono due endpoint per generare contenuti. La differenza principale è il modo in cui ricevi la risposta:

  • generateContent (REST): Riceve una richiesta e fornisce una singola risposta dopo che il modello ha terminato l'intera generazione.
  • streamGenerateContent (SSE): riceve la stessa richiesta, ma il modello trasmette in streaming blocchi della risposta man mano che vengono generati. Ciò offre una migliore esperienza utente per le applicazioni interattive, in quanto consente di visualizzare immediatamente i risultati parziali.

Struttura del corpo della richiesta

Il corpo della richiesta è un oggetto JSON identico per le modalità standard e di streaming ed è composto da alcuni oggetti principali:

  • Oggetto Content: rappresenta un singolo turno in una conversazione.
  • Oggetto Part: un insieme di dati all'interno di un turno Content (come testo o un'immagine).
  • inline_data (Blob): un contenitore per i byte multimediali non elaborati e il relativo tipo MIME.

Al livello più alto, il corpo della richiesta contiene un oggetto contents, che è un elenco di oggetti Content, ognuno dei quali rappresenta i turni della conversazione. Nella maggior parte dei casi, per la generazione di testo di base, avrai un singolo oggetto Content, ma se vuoi mantenere la cronologia delle conversazioni, puoi utilizzare più oggetti Content.

Di seguito è riportato un corpo della richiesta generateContent tipico:

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

Struttura del corpo della risposta

Il corpo della risposta è simile per le modalità di streaming e standard, ad eccezione di quanto segue:

A livello generale, il corpo della risposta contiene un oggetto candidates, che è un elenco di oggetti Candidate. L'oggetto Candidate contiene un oggetto Content che include la risposta generata restituita dal modello.

Esempi di richieste

I seguenti esempi mostrano come questi componenti si combinano per diversi tipi di richieste.

Prompt di solo testo

Un prompt di testo semplice è costituito da un array contents con un singolo oggetto Content. L'array parts di questo oggetto, a sua volta, contiene un singolo oggetto Part con un campo 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 multimodale (testo e immagine)

Per fornire sia testo che un'immagine in un prompt, l'array parts deve contenere due oggetti Part: uno per il testo e uno per l'immagine 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?"},
      ]
    }]
  }'

Conversazioni multi-turno (chat)

Per creare una conversazione con più turni, definisci l'array contents con più oggetti Content. L'API utilizzerà l'intera cronologia come contesto per la risposta successiva. Il role di ogni oggetto Content deve alternarsi tra user e 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." }
        ]
      }
    ]
  }'

Concetti principali

  • Content è la busta: è il contenitore di primo livello per un turno di messaggio, che sia dell'utente o del modello.
  • Part consente la multimodalità: utilizza più oggetti Part all'interno di un singolo oggetto Content per combinare diversi tipi di dati (testo, immagine, URI video e così via).
  • Scegli il metodo di dati:
    • Per i contenuti multimediali piccoli e incorporati direttamente (come la maggior parte delle immagini), utilizza un Part con inline_data.
    • Per i file più grandi o che vuoi riutilizzare in più richieste, utilizza l'API File per caricare il file e farvi riferimento con una parte file_data.
  • Gestisci la cronologia delle conversazioni: per le applicazioni di chat che utilizzano l'API REST, crea l'array contents aggiungendo oggetti Content per ogni turno, alternando i ruoli "user" e "model". Se utilizzi un SDK, consulta la documentazione dell'SDK per il modo consigliato di gestire la cronologia delle conversazioni.

Esempi di risposte

I seguenti esempi mostrano come questi componenti si combinano per diversi tipi di richieste.

Risposta solo testo

Una semplice risposta di testo è costituita da un array candidates con uno o più oggetti content che contengono la risposta del modello.

Di seguito è riportato un esempio di risposta standard:

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

Di seguito è riportata una serie di risposte relative allo streaming. Ogni risposta contiene un responseId che lega insieme l'intera risposta:

{
  "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) WebSockets

L'API Live offre un'API basata su WebSocket stateful per lo streaming bidirezionale per abilitare casi d'uso di streaming in tempo reale. Per ulteriori dettagli, puoi consultare la guida all'API Live e il riferimento all'API Live.

Modelli specializzati

Oltre alla famiglia di modelli Gemini, l'API Gemini offre endpoint per modelli specializzati come Imagen, Lyria e modelli di incorporamento. Puoi consultare queste guide nella sezione Modelli.

API della piattaforma

Il resto degli endpoint consente di utilizzare funzionalità aggiuntive con gli endpoint principali descritti finora. Per saperne di più, consulta gli argomenti Modalità batch e API File nella sezione Guide.

Passaggi successivi

Se hai appena iniziato, consulta le seguenti guide, che ti aiuteranno a comprendere il modello di programmazione dell'API Gemini:

Potresti anche consultare le guide alle funzionalità, che introducono diverse funzionalità dell'API Gemini e forniscono esempi di codice: