Руководство по нативному формату Gemini

APIYI полностью поддерживает официальный нативный формат Gemini (эндпоинт /v1beta generateContent): укажите base_url на https://api.apiyi.com, и ваш существующий код Gemini и официальные SDKs мигрируют без проблем — преобразование формата не требуется. Эта страница основана на официальной документации Google (ai.google.dev/gemini-api/docs, по состоянию на июнь 2026 года). Все примеры готовы к копированию и вставке.

Почему нативный формат

Формат, совместимый с OpenAI, тоже может вызывать Gemini, но следующие возможности доступны только в нативном формате:

Полные элементы управления thinking: thinking_level (серия Gemini 3) / thinking_budget (серия 2.5), сводки мыслей, сигнатуры мыслей
Нативные мультимодальные Parts: встроенные изображения / аудио / видео, с управлением затратами media_resolution — см. Мультимодальность и выполнение кода
Инструмент выполнения кода: code_execution запускает Python в песочнице
Поля использования с детальной гранулярностью: thoughts_token_count, cached_content_token_count и другие

Для обычного текстового чата или для одной codebase для нескольких вендоров вместо этого используйте Режим, совместимый с OpenAI.

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

Используйте официальный унифицированный SDK Google google-genai (устаревший google-generative-ai был снят с поддержки 30 ноября 2025 (UTC)):

pip install google-genai

from google import genai

client = genai.Client(
    api_key="YOUR_API_KEY",  # your APIYI key
    http_options={"base_url": "https://api.apiyi.com"}
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Introduce yourself in one sentence"
)
print(response.text)

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({
  apiKey: 'YOUR_API_KEY',
  httpOptions: { baseUrl: 'https://api.apiyi.com' }
});

const response = await ai.models.generateContent({
  model: 'gemini-3.5-flash',
  contents: 'Introduce yourself in one sentence'
});
console.log(response.text);

curl "https://api.apiyi.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -d '{
    "contents": [{
      "parts": [{"text": "Introduce yourself in one sentence"}]
    }]
  }'

base_url — это https://api.apiyi.com (без /v1) — отличается от https://api.apiyi.com/v1 формата, совместимого с OpenAI. Используйте ваш ключ APIYI, а не ключ Google AI Studio.

Потоковая передача

stream = client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Write a short essay on quantum computing"
)

for chunk in stream:
    print(chunk.text, end="", flush=True)

Контролы рассуждения

Модели Gemini по умолчанию используют рассуждение, и для двух поколений используются разные параметры — их смешивание вызывает ошибку:

Серия модели	Параметр	Значения
Gemini 3 / 3.1 / 3.5	`thinking_level`	`minimal` (только семейство Flash) / `low` / `high` (по умолчанию)
Gemini 2.5	`thinking_budget`	лимит token (например, 0–8192); если не задано, модель управляет автоматически

Передача одновременно thinking_level и thinking_budget в модель серии Gemini 3 возвращает ошибку — выберите один вариант (для серии 3 используйте thinking_level).

from google.genai import types

# Gemini 3 series: level-based control
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Prove that the square root of 2 is irrational",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high")
    )
)

# Gemini 2.5 series: token-budget control
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Simple question, be quick",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=0)  # thinking off
    )
)

Выбор уровня: minimal для простых задач с низкой задержкой (классификация, извлечение); low для обычного чата; high для сложного рассуждения и кода. Токены рассуждения тарифицируются по ставке output — более высокие уровни стоят дороже.

Сводки мыслей и сигнатуры мыслей

Сводки мыслей: include_thoughts=True возвращает сводку рассуждения (части, где part.thought имеет значение True)
Сигнатуры мыслей: зашифрованное состояние рассуждения, представленное в Gemini 3. В многоходовых беседах (особенно при function calling) передавайте thought_signature из ответа обратно без изменений, чтобы модель могла продолжить цепочку рассуждения. Официальные SDK делают это автоматически; не удаляйте это поле в ручных REST-вызовах — см. Function Calling

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Analyze the time complexity of: def fib(n): return n if n <= 1 else fib(n-1) + fib(n-2)",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high", include_thoughts=True)
    )
)

for part in response.candidates[0].content.parts:
    if getattr(part, "thought", False):
        print(f"[Thought summary] {part.text}")
    else:
        print(f"[Final answer] {part.text}")

Общие параметры конфигурации

Передаются через config (GenerateContentConfig):

Параметр	Описание
`system_instruction`	System prompt
`temperature`	0–2. Google рекомендует оставлять значение по умолчанию 1.0 для серии Gemini 3 — снижение может ухудшить качество reasoning
`max_output_tokens`	Лимит вывода (включает thinking tokens)
`thinking_config`	Управление thinking, см. выше
`response_mime_type`	Установите `application/json`, чтобы принудительно вывести JSON
`response_schema`	Ограничение схемы для структурированного вывода JSON
`tools`	Объявления функций / `code_execution` и другие инструменты
`media_resolution`	Управление стоимостью мультимодального ввода, см. страницу Multimodal

Поля использования (usage_metadata)

usage = response.usage_metadata
print(f"Input: {usage.prompt_token_count}")
print(f"Output: {usage.candidates_token_count}")
print(f"Thinking: {usage.thoughts_token_count}")
print(f"Cache hits: {usage.cached_content_token_count}")

Поле	Описание	Тарификация
`prompt_token_count`	Входные tokens	Тариф на вход
`candidates_token_count`	Выходные tokens	Тариф на выход
`thoughts_token_count`	tokens для рассуждения	Тариф на выход — настройте уровень, чтобы экономить
`cached_content_token_count`	Кэшированные tokens	Официальная скидка, см. Тарификация кэша
`total_token_count`	Итого	—

Поддерживаемые модели и тарификация

Модель	Ввод (за 1M tokens)	Вывод (за 1M tokens)	Примечания
`gemini-3.5-flash`	$1.50	$9.00	Текущая рабочая лошадка — превосходит 3.1 Pro по нескольким бенчмаркам, контекст 1M
`gemini-3.1-pro-preview`	$1.80	$10.80	Флагман Pro
`gemini-3-pro-preview`	$1.80	$10.80	Предыдущий Pro
`gemini-3-flash-preview`	$0.44	$2.64	Легкая и быстрая
`gemini-3.1-flash-lite`	$0.25	$1.50	Сверхбюджетная
`gemini-2.5-pro`	$1.25	$10.00	Pro серии 2.5
`gemini-2.5-flash`	$0.30	$2.40	Рабочая лошадка серии 2.5
`gemini-2.5-flash-lite`	$0.10	$0.40	Самая дешевая

Некоторые модели имеют варианты alias -thinking / -nothinking (например, gemini-3-flash-preview-nothinking), которые фиксируют thinking включенным/выключенным — удобно для клиентов, где вы не можете менять параметры запроса. Полный список: Модели и тарификация.

Нативный vs OpenAI-compatible

Функция	Gemini нативный	Совместимый с OpenAI
base_url	`https://api.apiyi.com`	`https://api.apiyi.com/v1`
SDK	`google-genai`	`openai`
Управление рассуждением	`thinking_level` / `thinking_budget`	`reasoning_effort`
Сводки / сигнатуры мыслей	✅	❌
Инструмент выполнения кода	✅	❌
Входные медиа	Нативные встроенные Parts (PIL / bytes)	Base64 image_url
Поле попадания в кэш	`cached_content_token_count`	`cached_tokens`

Примечания

Files API не поддерживается (client.files.upload()); медиа необходимо передавать inline, и каждый файл должен быть меньше 20MB — см. Мультимодальность и выполнение кода
Скидки за кэширование и ожидаемый уровень попаданий: Тарификация кэша

Связанные ссылки

Эта группа: Multimodal & Code Execution · Billing кэширования · Function Calling
Получение / управление tokens: https://api.apiyi.com/token
Официальная документация Google: ai.google.dev/gemini-api/docs

Основы

Базовый API

Image API (официальный)

Video API (официальный)

API мультимодального понимания

Текстовый API

Руководство по нативному формату Gemini

Почему нативный формат

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

Потоковая передача

Контролы рассуждения

Сводки мыслей и сигнатуры мыслей

Общие параметры конфигурации

Поля использования (usage_metadata)

Поддерживаемые модели и тарификация

Нативный vs OpenAI-compatible

Примечания

Связанные ссылки

​Почему нативный формат

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

​Потоковая передача

​Контролы рассуждения

​Сводки мыслей и сигнатуры мыслей

​Общие параметры конфигурации

​Поля использования (usage_metadata)

​Поддерживаемые модели и тарификация

​Нативный vs OpenAI-compatible

​Примечания

​Связанные ссылки

Почему нативный формат

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

Потоковая передача

Контролы рассуждения

Сводки мыслей и сигнатуры мыслей

Общие параметры конфигурации

Поля использования (usage_metadata)

Поддерживаемые модели и тарификация

Нативный vs OpenAI-compatible

Примечания

Связанные ссылки