Riferimento API
Guide all'integrazione
Prezzi e fatturazione
Modelli di testo
Gemini Generazione di contenuti
Usa il formato API nativo di Gemini tramite CometAPI per generazione di testo, input multimodale, thinking/reasoning, function calling, grounding con Google Search, modalità JSON e streaming.
POST
/
v1beta
/
models
/
{model}
:
{operator}
from google import genai
client = genai.Client(
api_key="<COMETAPI_KEY>",
http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
)
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Explain how AI works in a few words",
)
print(response.text){
"candidates": [
{
"content": {
"role": "<string>",
"parts": [
{
"text": "<string>",
"functionCall": {
"name": "<string>",
"args": {}
},
"inlineData": {
"mimeType": "<string>",
"data": "<string>"
},
"thought": true
}
]
},
"finishReason": "STOP",
"safetyRatings": [
{
"category": "<string>",
"probability": "<string>",
"blocked": true
}
],
"citationMetadata": {
"citationSources": [
{
"startIndex": 123,
"endIndex": 123,
"uri": "<string>",
"license": "<string>"
}
]
},
"tokenCount": 123,
"avgLogprobs": 123,
"groundingMetadata": {
"groundingChunks": [
{
"web": {
"uri": "<string>",
"title": "<string>"
}
}
],
"groundingSupports": [
{
"groundingChunkIndices": [
123
],
"confidenceScores": [
123
],
"segment": {
"startIndex": 123,
"endIndex": 123,
"text": "<string>"
}
}
],
"webSearchQueries": [
"<string>"
]
},
"index": 123
}
],
"promptFeedback": {
"blockReason": "SAFETY",
"safetyRatings": [
{
"category": "<string>",
"probability": "<string>",
"blocked": true
}
]
},
"usageMetadata": {
"promptTokenCount": 123,
"candidatesTokenCount": 123,
"totalTokenCount": 123,
"trafficType": "<string>",
"thoughtsTokenCount": 123,
"promptTokensDetails": [
{
"modality": "<string>",
"tokenCount": 123
}
],
"candidatesTokensDetails": [
{
"modality": "<string>",
"tokenCount": 123
}
]
},
"modelVersion": "<string>",
"createTime": "<string>",
"responseId": "<string>"
}Panoramica
CometAPI supporta il formato API nativo di Gemini, offrendoti accesso completo a funzionalità specifiche di Gemini come il controllo del thinking, il grounding con Google Search, le modalità native di generazione immagini e altro ancora. Usa questo endpoint quando hai bisogno di capacità non disponibili tramite l’endpoint chat compatibile con OpenAI.Avvio rapido
Sostituisci l’URL di base e la chiave API in qualsiasi SDK Gemini o client HTTP:| Impostazione | Valore predefinito Google | CometAPI |
|---|---|---|
| Base URL | generativelanguage.googleapis.com | api.cometapi.com |
| Chiave API | $GEMINI_API_KEY | $COMETAPI_KEY |
Sia le intestazioni
x-goog-api-key sia Authorization: Bearer sono supportate per l’autenticazione.Thinking (Reasoning)
I modelli Gemini possono eseguire reasoning interno prima di generare una risposta. Il metodo di controllo dipende dalla generazione del modello.- Gemini 3 (thinkingLevel)
- Gemini 2.5 (thinkingBudget)
I modelli Gemini 3 usano
thinkingLevel per controllare la profondità del reasoning. Livelli disponibili: MINIMAL, LOW, MEDIUM, HIGH.curl "https://api.cometapi.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $COMETAPI_KEY" \
-d '{
"contents": [{"parts": [{"text": "Explain quantum physics simply."}]}],
"generationConfig": {
"thinkingConfig": {"thinkingLevel": "LOW"}
}
}'
I modelli Gemini 2.5 usano
thinkingBudget per un controllo granulare a livello di token:0— disabilita il thinking-1— dinamico (decide il modello, predefinito)> 0— budget di token specifico (ad esempio,1024,2048)
curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $COMETAPI_KEY" \
-d '{
"contents": [{"parts": [{"text": "Solve this logic puzzle step by step."}]}],
"generationConfig": {
"thinkingConfig": {"thinkingBudget": 2048}
}
}'
L’uso di
thinkingLevel con i modelli Gemini 2.5 (o di thinkingBudget con i modelli Gemini 3) può causare errori. Usa il parametro corretto per la versione del tuo modello.Streaming
UsastreamGenerateContent?alt=sse come operator per ricevere Server-Sent Events mentre il modello genera contenuti. Ogni evento SSE contiene una riga data: con un oggetto JSON GenerateContentResponse.
curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $COMETAPI_KEY" \
--no-buffer \
-d '{
"contents": [{"parts": [{"text": "Write a short poem about the stars"}]}]
}'
Istruzioni di sistema
Guida il comportamento del modello durante l’intera conversazione consystemInstruction:
curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $COMETAPI_KEY" \
-d '{
"contents": [{"parts": [{"text": "What is 2+2?"}]}],
"systemInstruction": {
"parts": [{"text": "You are a math tutor. Always show your work."}]
}
}'
Modalità JSON
Forza un output JSON strutturato conresponseMimeType. Facoltativamente, fornisci un responseSchema per una validazione rigorosa dello schema:
curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $COMETAPI_KEY" \
-d '{
"contents": [{"parts": [{"text": "List 3 planets with their distances from the sun"}]}],
"generationConfig": {
"responseMimeType": "application/json"
}
}'
Grounding con Google Search
Abilita la ricerca web in tempo reale aggiungendo uno strumentogoogleSearch:
curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $COMETAPI_KEY" \
-d '{
"contents": [{"parts": [{"text": "Who won the euro 2024?"}]}],
"tools": [{"google_search": {}}]
}'
groundingMetadata con gli URL delle fonti e i punteggi di affidabilità.
Esempio di risposta
Una risposta tipica dall’endpoint Gemini di CometAPI:{
"candidates": [
{
"content": {
"role": "model",
"parts": [{"text": "Hello"}]
},
"finishReason": "STOP",
"avgLogprobs": -0.0023
}
],
"usageMetadata": {
"promptTokenCount": 5,
"candidatesTokenCount": 1,
"totalTokenCount": 30,
"trafficType": "ON_DEMAND",
"thoughtsTokenCount": 24,
"promptTokensDetails": [{"modality": "TEXT", "tokenCount": 5}],
"candidatesTokensDetails": [{"modality": "TEXT", "tokenCount": 1}]
},
"modelVersion": "gemini-2.5-flash",
"createTime": "2026-03-25T04:21:43.756483Z",
"responseId": "CeynaY3LDtvG4_UP0qaCuQY"
}
Il campo
thoughtsTokenCount in usageMetadata mostra quanti token il modello ha speso per il ragionamento interno, anche quando l’output del thinking non è incluso nella risposta.Differenze principali rispetto all’endpoint compatibile con OpenAI
| Funzionalità | Gemini Native (/v1beta/models/...) | OpenAI-Compatible (/v1/chat/completions) |
|---|---|---|
| Controllo del thinking | thinkingConfig con thinkingLevel / thinkingBudget | Non disponibile |
| Grounding con Google Search | tools: [\{"google_search": \{\}\}] | Non disponibile |
| Grounding con Google Maps | tools: [\{"googleMaps": \{\}\}] | Non disponibile |
| Modalità di generazione immagini | responseModalities: ["IMAGE"] | Non disponibile |
| Header di autenticazione | x-goog-api-key o Bearer | Solo Bearer |
| Formato della risposta | Formato nativo Gemini (candidates, parts) | Formato OpenAI (choices, message) |
Autorizzazioni
Your CometAPI key passed via the x-goog-api-key header. Bearer token authentication (Authorization: Bearer <key>) is also supported.
Parametri del percorso
The Gemini model ID to use. See the Models page for current Gemini model IDs.
Esempio:
"gemini-2.5-flash"
The operation to perform. Use generateContent for synchronous responses, or streamGenerateContent?alt=sse for Server-Sent Events streaming.
Opzioni disponibili:
generateContent, streamGenerateContent?alt=sse Esempio:
"generateContent"
Corpo
application/json
The conversation history and current input. For single-turn queries, provide a single item. For multi-turn conversations, include all previous turns.
Show child attributes
Show child attributes
System instructions that guide the model's behavior across the entire conversation. Text only.
Show child attributes
Show child attributes
Tools the model may use to generate responses. Supports function declarations, Google Search, Google Maps, and code execution.
Show child attributes
Show child attributes
Configuration for tool usage, such as function calling mode.
Show child attributes
Show child attributes
Safety filter settings. Override default thresholds for specific harm categories.
Show child attributes
Show child attributes
Configuration for model generation behavior including temperature, output length, and response format.
Show child attributes
Show child attributes
The name of cached content to use as context. Format: cachedContents/{id}. See the Gemini context caching documentation for details.
Risposta
200 - application/json
Successful response. For streaming requests, the response is a stream of SSE events, each containing a GenerateContentResponse JSON object prefixed with data:.
The generated response candidates.
Show child attributes
Show child attributes
Feedback on the prompt, including safety blocking information.
Show child attributes
Show child attributes
Token usage statistics for the request.
Show child attributes
Show child attributes
The model version that generated this response.
The timestamp when this response was created (ISO 8601 format).
Unique identifier for this response.
⌘I
from google import genai
client = genai.Client(
api_key="<COMETAPI_KEY>",
http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
)
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Explain how AI works in a few words",
)
print(response.text){
"candidates": [
{
"content": {
"role": "<string>",
"parts": [
{
"text": "<string>",
"functionCall": {
"name": "<string>",
"args": {}
},
"inlineData": {
"mimeType": "<string>",
"data": "<string>"
},
"thought": true
}
]
},
"finishReason": "STOP",
"safetyRatings": [
{
"category": "<string>",
"probability": "<string>",
"blocked": true
}
],
"citationMetadata": {
"citationSources": [
{
"startIndex": 123,
"endIndex": 123,
"uri": "<string>",
"license": "<string>"
}
]
},
"tokenCount": 123,
"avgLogprobs": 123,
"groundingMetadata": {
"groundingChunks": [
{
"web": {
"uri": "<string>",
"title": "<string>"
}
}
],
"groundingSupports": [
{
"groundingChunkIndices": [
123
],
"confidenceScores": [
123
],
"segment": {
"startIndex": 123,
"endIndex": 123,
"text": "<string>"
}
}
],
"webSearchQueries": [
"<string>"
]
},
"index": 123
}
],
"promptFeedback": {
"blockReason": "SAFETY",
"safetyRatings": [
{
"category": "<string>",
"probability": "<string>",
"blocked": true
}
]
},
"usageMetadata": {
"promptTokenCount": 123,
"candidatesTokenCount": 123,
"totalTokenCount": 123,
"trafficType": "<string>",
"thoughtsTokenCount": 123,
"promptTokensDetails": [
{
"modality": "<string>",
"tokenCount": 123
}
],
"candidatesTokensDetails": [
{
"modality": "<string>",
"tokenCount": 123
}
]
},
"modelVersion": "<string>",
"createTime": "<string>",
"responseId": "<string>"
}