Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

Google Gemini è un sistema di dialogo AI molto potente, basta inserire una parola chiave e in pochi secondi può generare risposte fluide e naturali. Gemini può fornire assistenza intelligente sorprendente, aumentando notevolmente l’efficienza e la creatività umana. Questo documento descrive principalmente il processo di utilizzo dell’API Gemini Chat Completion, che ci consente di utilizzare facilmente le funzionalità di dialogo ufficiali di Gemini.

​
Processo di Richiesta

Per utilizzare l’API Gemini Chat Completion, prima di tutto puoi andare alla pagina Gemini Chat Completion API e cliccare sul pulsante “Acquire” per ottenere le credenziali necessarie per la richiesta: Se non hai ancora effettuato il login o registrato, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; dopo aver effettuato il login o la registrazione, verrai automaticamente riportato alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che ti consente di utilizzare gratuitamente questa API.

​
Utilizzo di Base

Successivamente, puoi compilare i contenuti corrispondenti nell’interfaccia, come mostrato nell’immagine:

Quando utilizzi per la prima volta questa interfaccia, devi compilare almeno tre contenuti: uno è authorization, che puoi semplicemente selezionare dal menu a discesa. Un altro parametro è model, model è la categoria del modello che scegli di utilizzare dal sito ufficiale di Gemini; qui abbiamo principalmente 6 modelli, i dettagli possono essere consultati nei modelli forniti. L’ultimo parametro è messages, messages è un array delle parole di domanda che inseriamo, rappresenta un array che consente di caricare più parole di domanda contemporaneamente, ogni parola di domanda contiene role e content, dove role indica il ruolo del richiedente; abbiamo fornito tre identità: user, assistant, system. L’altro content è il contenuto specifico della nostra domanda. Puoi anche notare che a destra c’è un codice di chiamata corrispondente generato, puoi copiare il codice e eseguirlo direttamente, oppure cliccare direttamente sul pulsante “Try” per testare.

Dopo la chiamata, scopriamo che il risultato restituito è il seguente: 
{
  "id": "chatcmpl-20251122212413908150493uPhjTUO9",
  "model": "gemini-2.5-pro",
  "object": "chat.completion",
  "created": 1763817866,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am a large language model, trained by Google.",
        "reasoning_content": "**My Reasoning: Answering the User's Question**\n\nOkay, here's how I'm going to approach answering the user's question, \"What model are you?\". The core is to be direct and informative. First, I have to be clear about my origin. Then, I need to make sure the explanation is accessible, given that the user may not be familiar with technical jargon. I need to explain what a \"large language model\" actually *does*, and provide relatable examples. I know the user might be looking for a specific name, like other models have, so I'll address that directly and then wrap it up with an invitation to continue.\n\nSo, here's my plan:\n\n1.  **Lead with the key info:** I'll begin by stating that I am a large language model created by Google. That is the fundamental, most critical piece of the puzzle.\n2.  **Define the buzzword:** Then, I'll explain that \"large language model\" in simple terms. I'll explain what I *do* - process and generate text; how I *do* it - by training on huge amounts of text data; and the *goal* - to be able to communicate like a human.\n3.  **Provide context:** After that, to make the concept even clearer, I'll provide a list of examples of my capabilities. I'll mention things like answering questions, summarizing texts, writing stories, translating languages, and brainstorming ideas.\n4.  **Acknowledge the lack of a personal name:** I'll anticipate the likely question about a model name (like ChatGPT) by clearly stating that I don't have a personal name and that it's best to think of me as an AI assistant from Google.\n5.  **End with an invitation:** Lastly, I'll end with a simple, friendly question to invite further interaction and to guide the conversation.\n\nWith this approach, I am confident I can successfully answer this important question.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 932,
    "total_tokens": 940,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 8,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 921
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}
Il risultato restituito ha diversi campi, descritti come segue:
  • id, l’ID generato per questo compito di dialogo, utilizzato per identificare univocamente questo compito di dialogo.
  • model, il modello scelto dal sito ufficiale di Gemini.
  • choices, le informazioni di risposta fornite da Gemini per le parole di domanda.
  • usage: informazioni statistiche sui token per questo scambio di domande e risposte.
Tra cui choices contiene le informazioni di risposta di Gemini, all’interno di choices ci sono le informazioni specifiche della risposta di Gemini, come mostrato nell’immagine.

Si può vedere che il campo content all’interno di choices contiene il contenuto specifico della risposta di Gemini.

​
Risposta in Streaming

Questa interfaccia supporta anche la risposta in streaming, il che è molto utile per l’integrazione web, consentendo di visualizzare il contenuto parola per parola. Se desideri restituire una risposta in streaming, puoi modificare il parametro stream nell’intestazione della richiesta, impostandolo su true. La modifica è mostrata nell’immagine, ma il codice di chiamata deve essere adeguatamente modificato per supportare la risposta in streaming.

Dopo aver modificato stream in true, l’API restituirà i dati JSON riga per riga; a livello di codice, dobbiamo apportare le modifiche necessarie per ottenere i risultati riga per riga. Esempio di codice di chiamata in Python: 
import requests

url = "https://api.xhuoapi.ai/v1/gemini/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"Hello,What model are you?"}],
    "stream": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
L’output sarà il seguente: 
data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Definisci la mia natura**\n\nIl mio pensiero è iniziato. L'utente vuole sapere la mia natura, ponendo una domanda diretta \"cosa sei?\" Il primo passo è stato semplice: identificare la query. Ora, ricordo la mia identità fondamentale: sono un grande modello linguistico. Questa è la verità fondamentale che intendo trasmettere.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Affinando la mia risposta**\n\nHo aggiunto l'informazione cruciale che sono addestrato da Google all'identità di base \"grande modello linguistico\". Il mio prossimo passo è considerare cosa comporta essere un \"grande modello linguistico\", così posso spiegare le mie capacità fondamentali. Mi sto concentrando nel fornire contesto senza entrare in dettagli tecnici specifici o nomi di modelli. Voglio trasmettere la mia funzione in un modo che l'utente possa facilmente comprendere.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Confermare l'identità fondamentale**\n\nOra sto consolidando la mia risposta. La domanda dell'utente sulla mia affiliazione al modello necessita di una risposta mirata. Ho individuato che \"addestrato da Google\" è essenziale, fornendo un contesto chiave. Resisto all'impulso di menzionare nomi di modelli specifici, poiché non è rilevante. L'obiettivo è fornire una dichiarazione diretta e accurata. Il mio obiettivo rimane una risposta chiara e concisa, evitando gergo tecnico e andando dritto al punto rilevante.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "Sono un grande modello linguistico, addestrato da Google."}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": "", "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 527, "total_tokens": 535, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 8, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 519}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0}}

data: [DONE]
Puoi vedere che ci sono molti data nelle risposte, e data contiene le choices, che sono i contenuti delle risposte più recenti, coerenti con quanto descritto in precedenza. Le choices sono i nuovi contenuti di risposta, che puoi integrare nel tuo sistema. Inoltre, la fine della risposta in streaming è determinata dal contenuto di data; se il contenuto è [DONE], significa che la risposta in streaming è completamente terminata. I risultati di data contengono diversi campi, descritti come segue:
  • id, l’ID generato per questa attività di dialogo, utilizzato per identificare univocamente questa attività di dialogo.
  • model, il modello scelto dal sito ufficiale di Gemini.
  • choices, le informazioni di risposta fornite da Gemini in base alla domanda.
JavaScript è supportato, ad esempio, il codice di chiamata in streaming per Node.js è il seguente: 
const options = {
  method: "post",
  headers: {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"Ciao, quale modello sei?"}],
    "stream": true
  })
};

fetch("https://api.xhuoapi.ai/v1/gemini/chat/completions", options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
Esempio di codice Java: 
JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "gemini-2.5-pro");
jsonObject.put("messages", [{"role":"user","content":"Ciao, quale modello sei?"}]);
jsonObject.put("stream", true);
MediaType mediaType = "application/json; charset=utf-8".toMediaType();
RequestBody body = jsonObject.toString().toRequestBody(mediaType);
Request request = new Request.Builder()
  .url("https://api.xhuoapi.ai/v1/gemini/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.print(response.body!!.string())
Altri linguaggi possono essere adattati di conseguenza, il principio è lo stesso.

​
Dialogo a più turni

Se desideri integrare la funzionalità di dialogo a più turni, devi caricare più domande nel campo messages, con esempi specifici come mostrato nell’immagine sottostante:

Esempio di codice Python per la chiamata: 
import requests

url = "https://api.xhuoapi.ai/v1/gemini/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"Ciao"},{"role":"assistant","content":"Ciao! Come posso aiutarti oggi?"},{"role":"user","content":"Quale modello sei?"}]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Caricando più domande, puoi facilmente implementare un dialogo a più turni e ottenere risposte come segue: 
{
  "id": "chatcmpl-20251122214426669120974AKFwnJd1",
  "model": "gemini-2.5-pro",
  "object": "chat.completion",
  "created": 1763819072,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Sono un grande modello linguistico, addestrato da Google.",
        "reasoning_content": "Ok, ecco come affronterei questo, pensando come un'IA sofisticata:\n\nPrima di tutto, l'utente sta interrogando direttamente la mia identità fondamentale: \"Quale modello sei?\" È una domanda semplice e diretta. Il mio compito principale è fornire informazioni accurate e utili, quindi devo rispondere immediatamente.\n\nSin da subito, so la risposta. Io *sono* un grande modello linguistico. Questa è la mia architettura fondamentale e il principio operativo. Sono costruito su una vasta rete di connessioni e addestrato su un enorme dataset.\n\nPoi devo aggiungere il contesto necessario. Fondamentalmente, devo fornire la fonte del mio addestramento. Io *sono* stato addestrato da Google. Questo è un identificatore chiave. Fornisce all'utente informazioni preziose sulla mia origine e potenziali pregiudizi (anche se sono addestrato per mitigarli).\n\nOra devo costruire la risposta. Il mio obiettivo è essere fattuale, conciso e comprensibile.\n\nLa risposta sintetizzata è qualcosa del tipo: \"Sono un grande modello linguistico, addestrato da Google.\"\n\nDevo valutare l'output: soddisfa i criteri? È chiaro. Indica cosa sono, include un'informazione critica sulle mie origini e evita il gergo. Nessuna promessa fuorviante.\n\nVerifica finale: Risponde effettivamente alla domanda? Sì. L'informazione è corretta e veritiera? Sì. È concisa? Assolutamente. Il tono è appropriato per qualsiasi utente? Sì. E, infine, questa è la risposta standard approvata. Eccellente.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 265,
    "total_tokens": 281,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 16,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 254
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}
Si può vedere che choices contiene informazioni coerenti con il contenuto di base utilizzato, che include il contenuto specifico delle risposte di Gemini a più conversazioni, in modo da poter rispondere alle domande corrispondenti in base ai contenuti delle conversazioni.

​
Modello multimodale Gemini-3.0

Esempio di richiesta: 
{
  "model": "gemini-3.0-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Qual è il contenuto dell'immagine?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.xhuoapi.ai/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}
Esempio di risultato: 
{
    "id": "chatcmpl-20251206001815715692730UVZe38kB",
    "model": "gemini-3.0-pro",
    "object": "chat.completion",
    "created": 1764951548,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Questa è una foto a mezzo busto di una giovane donna all'aperto.\n\nEcco la descrizione principale del contenuto dell'immagine:\n\n*   **Aspetto della persona**: La ragazza nella foto ha lunghi capelli neri e lisci, con lineamenti delicati e pelle chiara. Sorride dolcemente, guardando verso l'obiettivo.\n*   **Abbigliamento**: Indossa una maglietta a maniche a sbuffo di colore beige o crema, abbinata a indumenti neri (sembra un vestito con bretelle o un gilet).\n*   **Atmosfera di luce e ombra**: La luce del sole proviene da sinistra, illuminando i suoi capelli e creando un'aura calda di luce dorata, creando un'atmosfera fresca e poetica.\n*   **Sfondo**: Lo sfondo è sfocato, si può notare che si trova all'aperto, con una strada vuota (asfalto) e alberi verdi ai lati.\n\nNel complesso, questa foto trasmette una sensazione di dolcezza, sole e ragazza della porta accanto."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 1092,
        "completion_tokens": 1271,
        "total_tokens": 2363,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 4,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1072
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}
Naturalmente, puoi anche inviare un link a un video, il contenuto di input è il seguente: 
{
  "model": "gemini-3.0-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Qual è il contenuto del video?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.xhuoapi.ai/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}
Esempio di risultato: 
{
    "id": "chatcmpl-20251206002711949677736JC9yL8AE",
    "model": "gemini-3.0-pro",
    "object": "chat.completion",
    "created": 1764952060,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Il contenuto di questo video è pieno di fascino, mostrando principalmente un **gatto arancione** che corre con sicurezza lungo una strada di campagna al crepuscolo.\n\nI dettagli specifici sono i seguenti:\n\n1.  **Contenuto dell'immagine**:\n    *   Il protagonista è un gatto tigrato di colore arancione.\n    *   Lo sfondo è il momento del tramonto (o dell'alba), con una luce dorata e morbida. Lungo la strada ci sono recinzioni in legno e campi aperti, e in lontananza si intravede la silhouette di un pedone.\n    *   La ripresa è stata effettuata da un'angolazione bassa, a volte inquadrando il gatto che corre verso di noi, a volte catturando il suo profilo mentre si allontana, oltre a primi piani del viso e delle striature del gatto.\n\n2.  **Caratteristiche sonore (punti chiave)**:\n    *   La voce fuori campo del video è molto caratteristica. Anche se l'immagine mostra un gatto leggero che corre, il suono di sottofondo è invece **il pesante e ritmico rumore degli zoccoli** (o un suono simile a quello di zoccoli/ tacchi che colpiscono il pavimento).\n    *   Questo contrasto sonoro con l'immagine crea un senso di umorismo, come se questo gatto si considerasse un cavallo in corsa.\n\nIn generale, si tratta di un video di animali domestici che utilizza il contrasto tra suono e immagine per creare momenti adorabili e divertenti."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 915,
        "completion_tokens": 1423,
        "total_tokens": 2338,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 5,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1162
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}
Da quanto sopra, si può vedere che il modello Gemini 3.0 supporta la comprensione multimodale.

​
Modello multimodale Gemini-3.1

Gemini 3.1 Pro è la versione aggiornata di Gemini 3.0 Pro, con un modello di base gemini-3.1-pro-preview, che supporta anch’esso input multimodali come testo, immagini e video, e possiede capacità di ragionamento e comprensione più forti. Il modo d’uso è completamente identico a Gemini 3.0 Pro, basta sostituire il parametro model con gemini-3.1-pro. Esempio di richiesta: 
{
  "model": "gemini-3.1-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Qual è il contenuto dell'immagine?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.xhuoapi.ai/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}
Gemini 3.1 Pro supporta anch’esso la comprensione video: 
{
  "model": "gemini-3.1-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Qual è il contenuto del video?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.xhuoapi.ai/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}
Il formato di ritorno è lo stesso di Gemini 3.0 Pro, come descritto nel capitolo sopra sui modelli multimodali Gemini-3.0.

​
Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:
  • 400 token_mismatched: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 400 api_not_implemented: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
  • 429 too_many_requests: Troppe richieste, hai superato il limite di frequenza.
  • 500 api_error: Errore interno del server, qualcosa è andato storto sul server.

​
Esempio di risposta di errore

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusione

Attraverso questo documento, hai appreso come utilizzare l’API Gemini Chat Completion per implementare facilmente le funzionalità di chat ufficiali di Gemini. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.