Generare contenuti

POST

v1beta

models

{model}

{operator}

import os
from google import genai

client = genai.Client(
    api_key=os.environ["COMETAPI_KEY"],
    http_options={
        "api_version": "v1beta",
        "base_url": "https://api.cometapi.com",
    },
)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents='Explain how AI works in a few words',
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "AI learns patterns from massive amounts of data to make predictions, solve problems, and generate new content. \n\nIn short: **Data in → Patterns found → Smart predictions out.**"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 36,
    "thoughtsTokenCount": 388,
    "totalTokenCount": 433
  },
  "modelVersion": "gemini-3.8-flash"
}

Utilizza il formato di richiesta nativo di Gemini tramite CometAPI per generare testo, inviare input video e configurare il ragionamento o gli strumenti. Gli esempi utilizzano gemini-3.8-flash.

Utilizza il riferimento API GenerateContent di Google Riferimento API GenerateContent per le definizioni dei campi e le opzioni specifiche del modello. Questa pagina mostra l’URL di base CometAPI, l’autenticazione e gli esempi di richiesta.

Per l’autenticazione sono supportate entrambe le intestazioni x-goog-api-key e Authorization: Bearer.

Guida rapida

Per utilizzare Google Gen AI SDK o un client HTTP con CometAPI, configura 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`

Utilizza la Guida alla generazione di testo GenerateContent per esempi di API nativa. Mantieni la struttura della richiesta generateContent quando modifichi l’URL di base.

Inviare input video

Invia il video come parte del contenuto. Scegli il formato di input in base a dove è archiviato il video:

Origine del video	Parte della richiesta	Utilizza quando
File video locale	`inlineData`	Il video è abbastanza piccolo da poter essere inviato come base64 nella richiesta JSON.
URL pubblico del video	`fileData.fileUri`	Il video è disponibile tramite un URL HTTPS pubblico che non richiede autenticazione.

Per le richieste REST e curl, utilizza nomi di campi camelCase come inlineData.mimeType e fileData.fileUri.

Questo esempio invia dati MP4 inline. Sostituisci <base64-encoded-mp4> con il contenuto base64 del tuo video:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "video/mp4",
            "data": "<base64-encoded-mp4>"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 2048,
    "thinkingConfig": {
      "thinkingLevel": "LOW"
    }
  }
}
EOF

Questo esempio analizza un MP4 pubblico di un fiore che si apre:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 2048,
    "thinkingConfig": {
      "thinkingLevel": "LOW"
    }
  }
}
EOF

Configurare il ragionamento (ragionamento)

Usa thinkingConfig.thinkingLevel per definire la profondità del ragionamento. Gli esempi seguenti usano LOW e MEDIUM.

Livello di ragionamento
Riepiloghi del ragionamento

Questo esempio imposta il livello di ragionamento su LOW:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "How does quantum computing work?"
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "LOW"
    }
  }
}
EOF

Imposta includeThoughts per richiedere un riepilogo del ragionamento. Quando la risposta include un riepilogo, la relativa parte di testo contiene thought: true:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "What is the 10th Fibonacci number when F(0)=0 and F(1)=1? Briefly verify the result."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 4096,
    "thinkingConfig": {
      "thinkingLevel": "MEDIUM",
      "includeThoughts": true
    }
  }
}
EOF

thinkingBudget è un controllo numerico per i modelli compatibili, incluso Gemini 2.5. Usa thinkingLevel negli esempi Gemini 3 e non inviare entrambi i controlli. Consulta la guida di Google sul ragionamento per i valori specifici del modello.

Streaming delle risposte

Usa streamGenerateContent?alt=sse per ricevere Server-Sent Events. Ogni riga data: contiene un oggetto JSON GenerateContentResponse:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --no-buffer \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "Write a short poem about the stars"
        }
      ]
    }
  ]
}
EOF

Impostare le istruzioni di sistema

Usa systemInstruction per guidare la risposta. Questo esempio richiede un’equazione senza testo aggiuntivo:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "What is 2+2?"
        }
      ]
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are a math tutor. Answer with exactly one equation and no other text."
      }
    ]
  }
}
EOF

Richiedere output JSON

Imposta responseMimeType su application/json e fornisci un responseSchema. Questo esempio richiede un array di pianeti con nomi e distanze numeriche:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "Return a JSON array of 3 planets with name and average_distance_from_sun_au."
        }
      ]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "ARRAY",
      "items": {
        "type": "OBJECT",
        "properties": {
          "name": {
            "type": "STRING",
            "description": "Name of the planet."
          },
          "average_distance_from_sun_au": {
            "type": "NUMBER",
            "description": "Average distance from the Sun, in astronomical units."
          }
        },
        "required": [
          "name",
          "average_distance_from_sun_au"
        ]
      }
    }
  }
}
EOF

Grounding con Google Search

Aggiungi uno strumento googleSearch per richiedere il grounding con la ricerca. Questo esempio richiede il risultato della finale di UEFA EURO 2024:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "Use Google Search to find the winner and final score of the UEFA EURO 2024 final. Cite your sources."
        }
      ]
    }
  ],
  "tools": [
    {
      "googleSearch": {}
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 2048
  }
}
EOF

Quando viene utilizzata la ricerca, esamina groundingMetadata del candidato per query di ricerca, URL delle fonti e collegamenti tra le fonti e il testo della risposta.

Mantieni il contenuto della conversazione

Per le conversazioni multi-turno, invia il contenuto user e model precedente in contents. Gli esempi di chat dell’SDK mantengono questa cronologia per te. Per Function Calling, restituisci un functionResponse per ogni functionCall, con il name corrispondente e qualsiasi id restituito. Passa nuovamente il contenuto precedente del modello senza modificarlo, inclusi i campi thoughtSignature. La firma è opaca; non ricostruirla dal testo visualizzato.

Esempio di risposta

Una risposta di testo include il contenuto generato e l’utilizzo dei token. Questo esempio abbreviato omette i campi facoltativi:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "AI learns patterns from massive amounts of data to make predictions, solve problems, and generate new content. \n\nIn short: **Data in → Patterns found → Smart predictions out.**"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 36,
    "thoughtsTokenCount": 388,
    "totalTokenCount": 433
  },
  "modelVersion": "gemini-3.8-flash"
}

thoughtsTokenCount segnala i token di ragionamento interni, anche quando la risposta non include un riepilogo del ragionamento. Esamina ogni parte del contenuto; una risposta può contenere testo, riepiloghi o chiamate di funzione.

Confronta i formati delle richieste

Scegli l’endpoint nativo per i campi di richiesta e risposta Gemini. Consulta Chat Completions per il formato compatibile con OpenAI.

Campo	Gemini nativo	Chat compatibile con OpenAI
Input della conversazione	`contents` con `parts`	`messages`
ID modello	Nel percorso della richiesta	`model` nel corpo della richiesta
Contenuto generato	`candidates` con `content.parts`	`choices` con `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 $COMETAPI_KEY) is also supported.

Parametri del percorso

model

string

predefinito:gemini-3.8-flash

obbligatorio

Gemini model ID. These examples use gemini-3.8-flash. See the Models page for available model IDs.

operator

enum<string>

predefinito:generateContent

obbligatorio

Operation to perform. Use generateContent for a JSON response. For Server-Sent Events, select streamGenerateContent and set the separate alt query parameter to sse.

Opzioni disponibili:

generateContent,

streamGenerateContent

Parametri della query

alt

enum<string>

Set to sse when the operator is streamGenerateContent. Omit this parameter for generateContent.

Opzioni disponibili:

sse

Corpo

application/json

contents

object[]

Conversation content. Each entry has an optional role (user or model) and a parts array. For tool results, preserve the complete preceding model content, including any thoughtSignature fields.

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 available to the model during generation. Use googleSearch for search grounding.

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.

Ultima modifica il 8 settembre 2026

import os
from google import genai

client = genai.Client(
    api_key=os.environ["COMETAPI_KEY"],
    http_options={
        "api_version": "v1beta",
        "base_url": "https://api.cometapi.com",
    },
)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents='Explain how AI works in a few words',
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "AI learns patterns from massive amounts of data to make predictions, solve problems, and generate new content. \n\nIn short: **Data in → Patterns found → Smart predictions out.**"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 36,
    "thoughtsTokenCount": 388,
    "totalTokenCount": 433
  },
  "modelVersion": "gemini-3.8-flash"
}

Moderazione dei contenuti

Chiavi API

Guida rapida

Inviare input video

Configurare il ragionamento (ragionamento)

Streaming delle risposte

Impostare le istruzioni di sistema

Richiedere output JSON

Grounding con Google Search

Mantieni il contenuto della conversazione

Esempio di risposta

Confronta i formati delle richieste

Autorizzazioni

Parametri del percorso

Parametri della query

Corpo

Risposta

​Guida rapida

​Inviare input video

​Configurare il ragionamento (ragionamento)

​Streaming delle risposte

​Impostare le istruzioni di sistema

​Richiedere output JSON

​Grounding con Google Search

​Mantieni il contenuto della conversazione

​Esempio di risposta

​Confronta i formati delle richieste

Autorizzazioni

Parametri del percorso

Parametri della query

Corpo

Risposta

Guida rapida

Inviare input video

Configurare il ragionamento (ragionamento)

Streaming delle risposte

Impostare le istruzioni di sistema

Richiedere output JSON

Grounding con Google Search

Mantieni il contenuto della conversazione

Esempio di risposta

Confronta i formati delle richieste