Генерування контенту

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, Google Search grounding, нативні модальності генерації зображень та інше. Використовуйте цей endpoint, коли вам потрібні можливості, недоступні через OpenAI-compatible chat endpoint.

Використовуйте офіційний довідник Google GenerateContent API reference як авторитетне джерело повного переліку полів запиту, схеми відповіді та специфічної для моделей Gemini поведінки. Ця сторінка CometAPI пояснює, як надсилати цей нативний формат запиту через CometAPI.

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

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

Швидкий старт

Щоб використовувати будь-який SDK Gemini або HTTP-клієнт із CometAPI, замініть base 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-запитів використовуйте camelCase-імена полів Gemini, такі як 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"}]}]
  }'

Задання системних інструкцій

Щоб керувати поведінкою моделі протягом усієї розмови, використовуйте 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"
    }
  }'

Ground за допомогою 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 показує, скільки token модель витратила на внутрішнє міркування, навіть якщо результат thinking не включено у відповідь.

Порівняння з 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

Задання системних інструкцій

Запит JSON-виводу

Ground за допомогою Google Search

Приклад відповіді

Порівняння з OpenAI-compatible endpoint

Авторизації

Параметри шляху

Тіло

Відповідь

​Швидкий старт

​Надсилання відео як вхідних даних

​Налаштування thinking (reasoning)

​Потокові Responses

​Задання системних інструкцій

​Запит JSON-виводу

​Ground за допомогою Google Search

​Приклад відповіді

​Порівняння з OpenAI-compatible endpoint

Авторизації

Параметри шляху

Тіло

Відповідь

Швидкий старт

Надсилання відео як вхідних даних

Налаштування thinking (reasoning)

Потокові Responses

Задання системних інструкцій

Запит JSON-виводу

Ground за допомогою Google Search

Приклад відповіді

Порівняння з OpenAI-compatible endpoint