Справочник API
Руководства по интеграции
Цены и оплата
Текстовые модели
Gemini Генерация контента
Используйте нативный формат API Gemini через CometAPI для генерации текста, multimodal-ввода, thinking/reasoning, function calling, grounding через Google Search, JSON mode и 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>"
}Обзор
CometAPI поддерживает нативный формат API Gemini, предоставляя вам полный доступ к функциям Gemini, таким как управление thinking, grounding через Google Search, нативные modalities генерации изображений и многое другое. Используйте этот endpoint, когда вам нужны возможности, недоступные через совместимый с OpenAI chat endpoint.Быстрый старт
Замените базовый URL и API key в любом Gemini SDK или HTTP-клиенте:| Настройка | Значение по умолчанию Google | CometAPI |
|---|---|---|
| Базовый URL | generativelanguage.googleapis.com | api.cometapi.com |
| API key | $GEMINI_API_KEY | $COMETAPI_KEY |
Для аутентификации поддерживаются оба заголовка:
x-goog-api-key и Authorization: Bearer.Thinking (рассуждение)
Модели Gemini могут выполнять внутреннее рассуждение перед генерацией ответа. Способ управления зависит от поколения модели.- Gemini 3 (thinkingLevel)
- Gemini 2.5 (thinkingBudget)
Модели Gemini 3 используют
thinkingLevel для управления глубиной рассуждения. Доступные уровни: 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"}
}
}'
Модели Gemini 2.5 используют
thinkingBudget для более точного управления на уровне Token:0— отключить thinking-1— динамически (решает модель, значение по умолчанию)> 0— конкретный бюджет Token (например,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}
}
}'
Использование
thinkingLevel с моделями Gemini 2.5 (или thinkingBudget с моделями Gemini 3) может вызывать ошибки. Используйте правильный параметр для версии вашей модели.Streaming
ИспользуйтеstreamGenerateContent?alt=sse в качестве оператора, чтобы получать Server-Sent Events по мере генерации контента моделью. Каждое SSE-событие содержит строку data: с 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"}]}]
}'
Системные инструкции
Управляйте поведением модели на протяжении всего разговора с помощьюsystemInstruction:
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."}]
}
}'
JSON Mode
Принудительно задайте структурированный JSON-вывод с помощьюresponseMimeType. При необходимости можно также указать responseSchema для строгой валидации схемы:
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 через Google Search
Включите поиск в интернете в реальном времени, добавив инструментgoogleSearch:
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 с URL-адресами источников и оценками достоверности.
Пример ответа
Типичный ответ от Gemini endpoint в 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"
}
Поле
thoughtsTokenCount в usageMetadata показывает, сколько Tokens модель потратила на внутреннее рассуждение, даже если вывод процесса мышления не включён в ответ.Основные отличия от OpenAI-совместимого endpoint
| Возможность | Gemini Native (/v1beta/models/...) | OpenAI-Compatible (/v1/chat/completions) |
|---|---|---|
| Управление thinking | thinkingConfig с thinkingLevel / thinkingBudget | Недоступно |
| Grounding через Google Search | tools: [\{"google_search": \{\}\}] | Недоступно |
| Grounding через Google Maps | tools: [\{"googleMaps": \{\}\}] | Недоступно |
| Модальность генерации изображений | responseModalities: ["IMAGE"] | Недоступно |
| Заголовок авторизации | x-goog-api-key или Bearer | Только Bearer |
| Формат ответа | Gemini native (candidates, parts) | Формат OpenAI (choices, message) |
Авторизации
Your CometAPI key passed via the x-goog-api-key header. Bearer token authentication (Authorization: Bearer <key>) is also supported.
Параметры пути
The Gemini model ID to use. See the Models page for current Gemini model IDs.
Пример:
"gemini-2.5-flash"
The operation to perform. Use generateContent for synchronous responses, or streamGenerateContent?alt=sse for Server-Sent Events streaming.
Доступные опции:
generateContent, streamGenerateContent?alt=sse Пример:
"generateContent"
Тело
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.
Ответ
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>"
}