Generowanie treści

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 obsługuje natywny format API Gemini, dając Ci pełny dostęp do funkcji specyficznych dla Gemini, takich jak kontrola myślenia, osadzanie w Google Search, natywne modalności generowania obrazów i inne. Użyj tego endpointu, gdy potrzebujesz możliwości niedostępnych przez zgodny z OpenAI endpoint chat.

Używaj oficjalnego referencyjnego API GenerateContent Google jako autorytatywnego źródła pełnych pól żądania, schematu odpowiedzi i zachowania specyficznego dla modeli Gemini. Ta strona CometAPI wyjaśnia, jak wysłać ten natywny format żądania przez CometAPI.

Parametry żądań Gemini i pola odpowiedzi mogą się zmieniać, gdy Google aktualizuje natywne API. Sprawdź dokumentację generowania tekstu Gemini, aby zobaczyć najnowszą pełną listę parametrów i zachowania specyficzne dla dostawcy.

Do uwierzytelniania obsługiwane są zarówno nagłówki x-goog-api-key, jak i Authorization: Bearer.

Szybki start

Aby używać dowolnego SDK Gemini lub klienta HTTP z CometAPI, zamień bazowy URL i klucz API:

Ustawienie	Domyślne Google	CometAPI
Base URL	`generativelanguage.googleapis.com`	`api.cometapi.com`
Klucz API	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

Wysyłanie wejścia wideo

Gemini generateContent akceptuje wideo jako część content. Wybierz format wejścia w zależności od tego, gdzie przechowywane jest wideo:

Źródło wideo	Część żądania	Kiedy używać
Lokalny plik wideo	`inlineData`	Wideo jest na tyle małe, że można je wysłać jako base64 w żądaniu JSON.
Publiczny URL wideo	`fileData.fileUri`	Wideo jest dostępne przez publiczny adres URL HTTPS, który nie wymaga uwierzytelniania.

W przypadku żądań REST i curl używaj nazw pól Gemini w formacie camelCase, takich jak inlineData.mimeType i fileData.fileUri. Nie wysyłaj mediów URL jako file_data.file_uri.

Ten przykład odczytuje lokalny plik MP4, koduje go jako base64 i wysyła w treści żądania:

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

Ten przykład wysyła publiczny adres URL MP4 za pomocą 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 nie zaleca osobnego przepływu przesyłania przez Gemini Files API dla tego endpointu. Zamiast tego wyślij media bezpośrednio w żądaniu generateContent, używając inlineData lub fileData.fileUri.

Konfigurowanie thinking (reasoning)

Modele Gemini mogą wykonywać wewnętrzne rozumowanie przed wygenerowaniem odpowiedzi. Metoda sterowania zależy od generacji modelu.

Gemini 3 (thinkingLevel)
Gemini 2.5 (thinkingBudget)

Modele Gemini 3 używają thinkingLevel do kontrolowania głębokości rozumowania. Dostępne poziomy: MINIMAL, LOW, MEDIUM, HIGH.Używaj gemini-3-flash-preview jako domyślnego przykładowego modelu, chyba że potrzebujesz konkretnego innego wariantu 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"}
    }
  }'

Modele Gemini 2.5 używają thinkingBudget do szczegółowej kontroli na poziomie Token:

0 — wyłącz thinking
-1 — dynamicznie (model decyduje, domyślnie)
> 0 — określony budżet Token (np. 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}
    }
  }'

Użycie thinkingLevel z modelami Gemini 2.5 (lub thinkingBudget z modelami Gemini 3) może powodować błędy. Używaj poprawnego parametru dla wersji swojego modelu.

Stream odpowiedzi

Aby otrzymywać Server-Sent Events podczas generowania treści przez model, użyj streamGenerateContent?alt=sse jako operatora. Każde zdarzenie SSE zawiera linię data: z obiektem 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"}]}]
  }'

Ustawianie instrukcji systemowych

Aby kierować zachowaniem modelu w całej rozmowie, użyj 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."}]
    }
  }'

Żądanie wyjścia JSON

Aby wymusić uporządkowane wyjście JSON, ustaw responseMimeType. Opcjonalnie podaj responseSchema do ścisłej walidacji względem schematu:

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

Ground z Google Search

Aby włączyć wyszukiwanie w sieci w czasie rzeczywistym, dodaj narzędzie 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": {}}]
  }'

Odpowiedź zawiera groundingMetadata z adresami URL źródeł i ocenami pewności.

Przykład odpowiedzi

Typowa odpowiedź z endpointu Gemini w 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"
}

Pole thoughtsTokenCount w usageMetadata pokazuje, ile tokenów model zużył na wewnętrzne rozumowanie, nawet jeśli wynik myślenia nie jest uwzględniony w odpowiedzi.

Porównanie z endpointem kompatybilnym z OpenAI

Funkcja	Gemini Native (`/v1beta/models/...`)	Kompatybilny z OpenAI (`/v1/chat/completions`)
Kontrola myślenia	`thinkingConfig` z `thinkingLevel` / `thinkingBudget`	Niedostępne
Ugruntowanie w Google Search	`tools: [\{"google_search": \{\}\}]`	Niedostępne
Ugruntowanie w Google Maps	`tools: [\{"googleMaps": \{\}\}]`	Niedostępne
Modalność generowania obrazów	`responseModalities: ["IMAGE"]`	Niedostępne
Nagłówek uwierzytelniania	`x-goog-api-key` lub `Bearer`	Tylko `Bearer`
Format odpowiedzi	Format natywny Gemini (`candidates`, `parts`)	Format OpenAI (`choices`, `message`)

Autoryzacje

x-goog-api-key

string

header

wymagane

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

Parametry ścieżki

model

string

wymagane

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

operator

enum<string>

wymagane

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

Dostępne opcje:

generateContent,

streamGenerateContent?alt=sse

Treść

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.

Odpowiedź

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.

Utwórz wiadomość

Poprzedni

API do generowania i edycji obrazów

Następny

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

Moderacja treści

Klucze API

Szybki start

Wysyłanie wejścia wideo

Konfigurowanie thinking (reasoning)

Stream odpowiedzi

Ustawianie instrukcji systemowych

Żądanie wyjścia JSON

Ground z Google Search

Przykład odpowiedzi

Porównanie z endpointem kompatybilnym z OpenAI

Autoryzacje

Parametry ścieżki

Treść

Odpowiedź

​Szybki start

​Wysyłanie wejścia wideo

​Konfigurowanie thinking (reasoning)

​Stream odpowiedzi

​Ustawianie instrukcji systemowych

​Żądanie wyjścia JSON

​Ground z Google Search

​Przykład odpowiedzi

​Porównanie z endpointem kompatybilnym z OpenAI

Autoryzacje

Parametry ścieżki

Treść

Odpowiedź

Szybki start

Wysyłanie wejścia wideo

Konfigurowanie thinking (reasoning)

Stream odpowiedzi

Ustawianie instrukcji systemowych

Żądanie wyjścia JSON

Ground z Google Search

Przykład odpowiedzi

Porównanie z endpointem kompatybilnym z OpenAI