Генерация контента

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 поддерживает нативный формат API Gemini, предоставляя вам полный доступ к функциям, специфичным для Gemini, таким как управление thinking, grounding через Google Search, нативные modalities для генерации изображений и многое другое. Используйте этот endpoint, когда вам нужны возможности, недоступные через совместимый с OpenAI endpoint чата.

Используйте официальный справочник API GenerateContent от Google как основной источник полной информации о полях запроса, схеме ответа и поведении, зависящем от конкретной модели Gemini. Эта страница CometAPI объясняет, как отправлять этот нативный формат запроса через CometAPI.

Параметры запроса Gemini и поля ответа могут изменяться по мере того, как Google обновляет нативный API. Проверьте документацию Gemini по генерации текста, чтобы получить актуальный полный список параметров и сведения о поведении, специфичном для провайдера.

Для аутентификации поддерживаются оба заголовка: x-goog-api-key и Authorization: Bearer.

Быстрый старт

Чтобы использовать любой Gemini SDK или HTTP-клиент с CometAPI, замените базовый URL и API key:

Параметр	Значение Google по умолчанию	CometAPI
Base URL	`generativelanguage.googleapis.com`	`api.cometapi.com`
API key	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

Отправка видео в качестве входных данных

Gemini generateContent принимает видео как часть content. Выберите форму входных данных в зависимости от того, где хранится видео:

Источник видео	Часть запроса	Когда использовать
Локальный видеофайл	`inlineData`	Видео достаточно небольшое, чтобы отправить его как base64 в JSON-запросе.
Публичный URL видео	`fileData.fileUri`	Видео доступно по публичному HTTPS URL, который не требует аутентификации.

Для запросов REST и curl используйте имена полей Gemini в camelCase, такие как inlineData.mimeType и fileData.fileUri. Не отправляйте URL-медиа как file_data.file_uri.

В этом примере читается локальный MP4-файл, кодируется в base64 и отправляется в теле запроса:

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

В этом примере отправляется публичный MP4 URL с 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 не рекомендует отдельный процесс загрузки через Gemini Files API для этого endpoint. Отправляйте медиа в самом запросе generateContent, используя inlineData или fileData.fileUri.

Настройка thinking (reasoning)

Модели Gemini могут выполнять внутреннее рассуждение перед генерацией ответа. Способ управления зависит от поколения модели.

Gemini 3 (thinkingLevel)
Gemini 2.5 (thinkingBudget)

Модели Gemini 3 используют thinkingLevel для управления глубиной рассуждения. Доступные уровни: MINIMAL, LOW, MEDIUM, HIGH.Используйте gemini-3-flash-preview в качестве модели-примера по умолчанию, если вам не нужен конкретный другой вариант 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"}
    }
  }'

Модели 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) может вызывать ошибки. Используйте правильный параметр для версии вашей модели.

Потоковые Responses

Чтобы получать Server-Sent Events по мере генерации контента моделью, используйте streamGenerateContent?alt=sse в качестве оператора. Каждое событие SSE содержит строку data: с 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"}]}]
  }'

Задание system instructions

Чтобы управлять поведением модели на протяжении всего разговора, используйте 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."}]
    }
  }'

Запрос вывода в JSON

Чтобы принудительно включить структурированный JSON-вывод, задайте responseMimeType. При необходимости можно также указать responseSchema для строгой валидации схемы:

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 с Google Search

Чтобы включить поиск в интернете в реальном времени, добавьте инструмент 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": {}}]
  }'

Ответ включает 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-3-flash-preview",
  "createTime": "2026-03-25T04:21:43.756483Z",
  "responseId": "CeynaY3LDtvG4_UP0qaCuQY"
}

Поле thoughtsTokenCount в usageMetadata показывает, сколько токенов модель потратила на внутреннее рассуждение, даже если thinking output не включён в ответ.

Сравнение с OpenAI-compatible 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 (`candidates`, `parts`)	Формат OpenAI (`choices`, `message`)

Авторизации

x-goog-api-key

string

header

обязательно

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

Параметры пути

model

string

обязательно

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

operator

enum<string>

обязательно

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

Доступные опции:

generateContent,

streamGenerateContent?alt=sse

Тело

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.

Ответ

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.

Создать сообщение

API для генерации и редактирования изображений

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

Модерация контента

API-ключи

Быстрый старт

Отправка видео в качестве входных данных

Настройка thinking (reasoning)

Потоковые Responses

Задание system instructions

Запрос вывода в JSON

Grounding с Google Search

Пример ответа

Сравнение с OpenAI-compatible endpoint

Авторизации

Параметры пути

Тело

Ответ

​Быстрый старт

​Отправка видео в качестве входных данных

​Настройка thinking (reasoning)

​Потоковые Responses

​Задание system instructions

​Запрос вывода в JSON

​Grounding с Google Search

​Пример ответа

​Сравнение с OpenAI-compatible endpoint

Авторизации

Параметры пути

Тело

Ответ

Быстрый старт

Отправка видео в качестве входных данных

Настройка thinking (reasoning)

Потоковые Responses

Задание system instructions

Запрос вывода в JSON

Grounding с Google Search

Пример ответа

Сравнение с OpenAI-compatible endpoint