Gemini Generating Content - CometAPI Documentation

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-3-flash-preview",
    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
          }
        ]
      },
      "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": {
    "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>"
}

CometAPI supporta il formato API nativo di Gemini, offrendoti pieno accesso a funzionalità specifiche di Gemini come il controllo del thinking, il grounding con Google Search, le modalità native di generazione di immagini e altro ancora. Usa questo endpoint quando hai bisogno di capacità non disponibili tramite l’endpoint chat compatibile con OpenAI.

Per l’autenticazione sono supportati sia gli header x-goog-api-key sia Authorization: Bearer.

Avvio rapido

Per usare qualsiasi SDK Gemini o client HTTP con CometAPI, sostituisci l’URL di base e la chiave API:

Impostazione	Predefinito Google	CometAPI
URL di base	`generativelanguage.googleapis.com`	`api.cometapi.com`
Chiave API	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

Configurare il 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.Usa gemini-3-flash-preview come model ID di esempio predefinito, a meno che tu non abbia bisogno specificamente di una variante diversa di Gemini 3.

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-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 es. 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.

Trasmettere risposte in streaming

Per ricevere Server-Sent Events mentre il modello genera contenuto, usa streamGenerateContent?alt=sse come operator. Ogni evento SSE contiene una riga data: con un oggetto JSON GenerateContentResponse.

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview: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"}]}]
  }'

Impostare le istruzioni di sistema

Per guidare il comportamento del modello nell’intera conversazione, usa systemInstruction:

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview: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."}]
    }
  }'

Output JSON della richiesta

Per forzare un output JSON strutturato, imposta responseMimeType. Facoltativamente, fornisci un responseSchema per una rigorosa validazione dello schema:

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview: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

Per abilitare la ricerca web in tempo reale, aggiungi uno strumento googleSearch:

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview: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": {}}]
  }'

La risposta include groundingMetadata con gli URL delle fonti e i punteggi di confidenza.

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-3-flash-preview",
  "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 di thinking non è incluso nella risposta.

Confronto con l’endpoint compatibile con OpenAI

Funzionalità	Gemini nativo (`/v1beta/models/...`)	Compatibile con OpenAI (`/v1/chat/completions`)
Controllo del thinking	`thinkingConfig` con `thinkingLevel` / `thinkingBudget`	Non disponibile
Grounding di Google Search	`tools: [\{"google_search": \{\}\}]`	Non disponibile
Grounding di 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

x-goog-api-key

string

header

obbligatorio

Your CometAPI key passed via the x-goog-api-key header. Bearer token authentication (Authorization: Bearer <key>) is also supported.

Parametri del percorso

model

string

obbligatorio

Gemini model ID. Example: gemini-3-flash-preview, gemini-2.5-pro. See the Models page for current options.

operator

enum<string>

obbligatorio

The operation to perform. Use generateContent for synchronous responses, or streamGenerateContent?alt=sse for Server-Sent Events streaming.

Opzioni disponibili:

generateContent,

streamGenerateContent?alt=sse

Corpo

application/json

contents

object[]

Show child attributes

systemInstruction

object

System instructions that guide the model's behavior across the entire conversation. Text only.

Show child attributes

tools

object[]

Tools the model may use to generate responses. Supports function declarations, Google Search, Google Maps, and code execution.

Show child attributes

toolConfig

object

Configuration for tool usage, such as function calling mode.

Show child attributes

safetySettings

object[]

Safety filter settings. Override default thresholds for specific harm categories.

Show child attributes

generationConfig

object

Configuration for model generation behavior including temperature, output length, and response format.

Show child attributes

cachedContent

string

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:.

candidates

object[]

The generated response candidates.

Show child attributes

promptFeedback

object

Feedback on the prompt, including safety blocking information.

Show child attributes

usageMetadata

object

Token usage statistics for the request.

Show child attributes

modelVersion

string

The model version that generated this response.

createTime

string

The timestamp when this response was created (ISO 8601 format).

responseId

string

Unique identifier for this response.

Anthropic Messages

Embeddings

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-3-flash-preview",
    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
          }
        ]
      },
      "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": {
    "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>"
}

Documentation Index

​Avvio rapido

​Configurare il thinking (reasoning)

​Trasmettere risposte in streaming

​Impostare le istruzioni di sistema

​Output JSON della richiesta

​Grounding con Google Search

​Esempio di risposta

​Confronto con l’endpoint compatibile con OpenAI

Autorizzazioni

Parametri del percorso

Corpo

Risposta

Avvio rapido

Configurare il thinking (reasoning)

Trasmettere risposte in streaming

Impostare le istruzioni di sistema

Output JSON della richiesta

Grounding con Google Search

Esempio di risposta

Confronto con l’endpoint compatibile con OpenAI