Générer du contenu

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-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 prend en charge le format natif de l’API Gemini, vous donnant un accès complet aux fonctionnalités spécifiques à Gemini comme le contrôle de la réflexion, l’ancrage Google Search, les modalités natives de génération d’images, et plus encore. Utilisez ce point de terminaison lorsque vous avez besoin de capacités non disponibles via le point de terminaison de chat compatible OpenAI.

Utilisez la référence officielle de l’API GenerateContent de Google comme source faisant autorité pour l’ensemble des champs de requête, le schéma de réponse et le comportement spécifique aux modèles Gemini. Cette page CometAPI explique comment envoyer cette structure de requête native via CometAPI.

Les paramètres de requête Gemini et les champs de réponse peuvent changer à mesure que Google met à jour l’API native. Consultez la documentation sur la génération de texte Gemini pour obtenir la liste complète la plus récente des paramètres et le comportement spécifique au fournisseur.

Les en-têtes x-goog-api-key et Authorization: Bearer sont tous deux pris en charge pour l’authentification.

Démarrage rapide

Pour utiliser n’importe quel SDK Gemini ou client HTTP avec CometAPI, remplacez l’URL de base et la clé API :

Paramètre	Valeur par défaut Google	CometAPI
URL de base	`generativelanguage.googleapis.com`	`api.cometapi.com`
Clé API	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

Envoyer une entrée vidéo

Gemini generateContent accepte la vidéo comme partie de contenu. Choisissez le format d’entrée selon l’endroit où la vidéo est stockée :

Source vidéo	Partie de requête	À utiliser quand
Fichier vidéo local	`inlineData`	La vidéo est assez petite pour être envoyée en base64 dans la requête JSON.
URL vidéo publique	`fileData.fileUri`	La vidéo est disponible via une URL HTTPS publique qui ne nécessite pas d’authentification.

Pour les requêtes REST et curl, utilisez les noms de champs en camelCase de Gemini comme inlineData.mimeType et fileData.fileUri. N’envoyez pas de média par URL sous la forme file_data.file_uri.

Cet exemple lit un fichier MP4 local, l’encode en base64 et l’envoie dans le corps de la requête :

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
VIDEO_PATH="./your_video.mp4"
VIDEO_B64=$(base64 < "$VIDEO_PATH" | tr -d '\n')

curl -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.5-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": "${VIDEO_B64}"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "thinkingConfig": {"thinkingLevel": "MINIMAL"}
  }
}
EOF

Cet exemple envoie une URL MP4 publique avec fileData.fileUri :

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
VIDEO_URL="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"

curl -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.5-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": "${VIDEO_URL}"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "thinkingConfig": {"thinkingLevel": "MINIMAL"}
  }
}
EOF

CometAPI ne recommande pas un flux de téléversement séparé via l’API Gemini Files pour ce point de terminaison. Envoyez plutôt le média dans la requête generateContent elle-même avec inlineData ou fileData.fileUri.

Configurer le thinking (reasoning)

Les modèles Gemini peuvent effectuer un raisonnement interne avant de générer une réponse. La méthode de contrôle dépend de la génération du modèle.

Gemini 3 (thinkingLevel)
Gemini 2.5 (thinkingBudget)

Les modèles Gemini 3 utilisent thinkingLevel pour contrôler la profondeur du raisonnement. Niveaux disponibles : MINIMAL, LOW, MEDIUM, HIGH.Utilisez gemini-3-flash-preview comme modèle d’exemple par défaut, sauf si vous avez spécifiquement besoin d’une autre variante de 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"}
    }
  }'

Les modèles Gemini 2.5 utilisent thinkingBudget pour un contrôle précis au niveau des tokens :

0 — désactiver le thinking
-1 — dynamique (le modèle décide, par défaut)
> 0 — budget de tokens spécifique (par ex. 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’utilisation de thinkingLevel avec les modèles Gemini 2.5 (ou de thinkingBudget avec les modèles Gemini 3) peut provoquer des erreurs. Utilisez le bon paramètre pour la version de votre modèle.

Streaming des réponses

Pour recevoir des événements envoyés par le serveur à mesure que le modèle génère du contenu, utilisez streamGenerateContent?alt=sse comme opérateur. Chaque événement SSE contient une ligne data: avec un objet 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"}]}]
  }'

Définir des instructions système

Pour guider le comportement du modèle sur l’ensemble de la conversation, utilisez 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."}]
    }
  }'

Demander une sortie JSON

Pour forcer une sortie JSON structurée, définissez responseMimeType. Vous pouvez éventuellement fournir un responseSchema pour une validation stricte du schéma :

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

Ancrer avec Google Search

Pour activer la recherche web en temps réel, ajoutez un outil 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 réponse inclut groundingMetadata avec les URL des sources et les scores de confiance.

Exemple de réponse

Une réponse typique du point de terminaison Gemini de 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"
}

Le champ thoughtsTokenCount dans usageMetadata indique combien de tokens le modèle a consacrés au raisonnement interne, même lorsque la sortie de réflexion n’est pas incluse dans la réponse.

Comparer avec le point de terminaison compatible OpenAI

Fonctionnalité	Gemini natif (`/v1beta/models/...`)	Compatible OpenAI (`/v1/chat/completions`)
Contrôle de la réflexion	`thinkingConfig` avec `thinkingLevel` / `thinkingBudget`	Non disponible
Ancrage Google Search	`tools: [\{"google_search": \{\}\}]`	Non disponible
Ancrage Google Maps	`tools: [\{"googleMaps": \{\}\}]`	Non disponible
Modalité de génération d’image	`responseModalities: ["IMAGE"]`	Non disponible
En-tête d’authentification	`x-goog-api-key` ou `Bearer`	`Bearer` uniquement
Format de réponse	Format natif Gemini (`candidates`, `parts`)	Format OpenAI (`choices`, `message`)

Autorisations

x-goog-api-key

string

header

requis

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

Paramètres de chemin

model

string

requis

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

operator

enum<string>

requis

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

Options disponibles:

generateContent,

streamGenerateContent?alt=sse

Corps

application/json

contents

object[]

Conversation content. Each entry has an optional role (user or model) and a parts array.

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.

Réponse

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.

Créer un message

API de génération et d’édition d’images

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

Modération de contenu

Clés API

Démarrage rapide

Envoyer une entrée vidéo

Configurer le thinking (reasoning)

Streaming des réponses

Définir des instructions système

Demander une sortie JSON

Ancrer avec Google Search

Exemple de réponse

Comparer avec le point de terminaison compatible OpenAI

Autorisations

Paramètres de chemin

Corps

Réponse

​Démarrage rapide

​Envoyer une entrée vidéo

​Configurer le thinking (reasoning)

​Streaming des réponses

​Définir des instructions système

​Demander une sortie JSON

​Ancrer avec Google Search

​Exemple de réponse

​Comparer avec le point de terminaison compatible OpenAI

Autorisations

Paramètres de chemin

Corps

Réponse

Démarrage rapide

Envoyer une entrée vidéo

Configurer le thinking (reasoning)

Streaming des réponses

Définir des instructions système

Demander une sortie JSON

Ancrer avec Google Search

Exemple de réponse

Comparer avec le point de terminaison compatible OpenAI