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

В этой статье с точки зрения ZSQH AI Gateway разобрано получение, настройка и вызов Gemini API Key, а также типичные ошибки.

Статья описывает распространённые версии на октябрь 2026 года. Интерфейс и квоты Google AI Studio могут меняться; ориентируйтесь на официальную консоль.

1. Что умеет Gemini API

Типичные сценарии:

  • Краткое изложение, перевод и переписывание длинных документов.
  • Понимание изображений и видео, модерация контента.
  • Мультимодальные вопросы и ответы, OCR, извлечение таблиц.
  • Генерация и объяснение кода.
  • Узлы рассуждения в агентских процессах.

Модели Gemini обычно делятся на уровни Pro и Flash. Pro мощнее, Flash быстрее и дешевле. Актуальные имена моделей, длина контекста и цены — на странице цены на модели.

2. Два пути получения Gemini API Key

Вариант A: официальный ключ Google AI Studio

  1. Откройте Google AI Studio.
  2. Войдите под аккаунтом Google.
  3. Перейдите на страницу API Key и создайте ключ.
  4. Скопируйте ключ и сохраните в менеджере паролей.
  5. Привяжите платёжный аккаунт в проекте, если нужна повышенная квота.

Официальный ключ подходит, если доступ к Google стабилен, нужен прямой официальный канал и расход невелик.

Вариант B: ключ через ZSQH AI Gateway

  1. Откройте ZSQH AI Gateway, зарегистрируйтесь и войдите.
  2. Перейдите на страницу «API-ключи» и создайте ключ.
  3. Задайте лимит и срок действия.
  4. Пополните баланс.
  5. Скопируйте ключ.

Шлюз подходит, если доступ из Китая нестабилен, нужен единый счёт и несколько моделей одновременно.

3. Какой Base URL указывать

Официальный Gemini API

Базовый URL нативного интерфейса Gemini:

https://generativelanguage.googleapis.com

Официально доступен и вход, совместимый с OpenAI:

https://generativelanguage.googleapis.com/v1beta/openai/

ZSQH AI Gateway

При использовании интерфейса, совместимого с OpenAI, укажите:

https://ai.zhongshangqihang.com/v1

Не смешивайте: официальный ключ — с официальным адресом, ключ шлюза — с адресом шлюза. При смешивании обычно возвращается 401 или 404.

4. Проверка через curl

export GEMINI_API_KEY="sk-ваш-ключ"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Объясни в трёх предложениях, что такое мультимодальная модель"}
    ]
  }'

Имя модели должно соответствовать текущему списку на странице цены на модели. Если возвращается model not found, сначала проверьте имя модели, а не ключ.

5. Вызов из Python

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {"role": "user", "content": "Кратко перечисли ключевые тезисы текста: " + "..."}
    ],
)

print(response.choices[0].message.content)

Если используете официальный SDK Google, установите google-genai по официальной документации и перейдите на официальный endpoint. Не смешивайте два пути.

6. Квоты и ограничения скорости

Квоты Gemini обычно считаются по модели, проекту, региону и временному окну. Распространённые ограничения:

  • запросов в минуту (RPM);
  • токенов в минуту (TPM);
  • запросов в день (RPD);
  • бесплатный и платный уровни различаются.

Фактические квоты — в официальной консоли Google или консоли шлюза. Для продакшена рекомендуется:

  1. задать лимит для ключа;
  2. применять экспоненциальную задержку при 429;
  3. подготовить резервную модель для критичных сценариев;
  4. отслеживать долю ошибок и задержку до первого токена.

7. Типичные проблемы доступа из Китая

Симптом Возможная причина Что делать
Тайм-аут соединения Сеть не достаёт до Google Использовать доступный шлюз или прокси
401 Неверный ключ или смешанный Base URL Проверить соответствие ключа и адреса
404 Лишний или пропущенный /v1 в пути Сверить официальный адрес и адрес шлюза отдельно
429 Превышены квота или частота Снизить параллельность, повторить, повысить квоту
Модель недоступна Регион или аккаунт не подключены Сменить модель или канал
Ответ обрезан Лимит вывода или контекста Изменить параметры или разбить на части

8. Как оценить стоимость

Стоимость Gemini обычно складывается из входных токенов, выходных токенов и мультимодального входа (изображения, видео). Порядок оценки:

  1. Посчитайте средние входные и выходные токены одного запроса.
  2. Узнайте текущую цену модели (см. цены на модели).
  3. Умножьте на число запросов в день — получите дневную стоимость.
  4. Добавьте расход на повторы, кэш и мультимодальный вход.

Не смотрите только на цену «за миллион токенов»: длинный контекст и мультимодальный вход часто составляют основную часть затрат.

9. Рекомендации по безопасности

  • Не встраивайте ключ во фронтенд.
  • Один ключ на человека, разделение по проектам.
  • Задавайте лимиты и срок действия.
  • Регулярно меняйте ключи.
  • В продакшене используйте переменные окружения или менеджер секретов.

Частые вопросы

Можно ли пользоваться Gemini API Key бесплатно?

Обычно есть бесплатный уровень, но с квотами и региональными ограничениями. Для долгосрочной или коммерческой работы лучше платный уровень; точные условия — в официальной политике.

Можно ли одним ключом вызывать Claude?

В шлюзе один ключ может вызывать несколько подключённых моделей; модель указывается в параметрах запроса. Официальный ключ Gemini даёт доступ только к моделям Google.

Почему одна и та же модель иногда отвечает медленно?

Причины — нагрузка вышестоящего провайдера, региональная сеть, длина контекста и параллельность. Для продакшена настройте тайм-ауты, повторы и резервный канал.

Что дальше

Если нужен стабильный доступ из Китая или единая точка входа для нескольких моделей, зарегистрируйтесь в ZSQH AI Gateway, создайте тестовый ключ, проверьте его через curl и подключайте приложение. Модели и цены — на странице цены на модели.

Читайте также: