Gemini API через generateContent: SDK, изображения, PDF, видео

Используйте нативный эндпоинт Gemini generateContent, если ваше приложение уже отправляет запросы в стиле Gemini. Направьте Google Gen AI SDK или свои запросы на https://api.laozhang.ai и подставьте API-ключ LaoZhang API.

Параметр	Значение
Запрос и ответ	Отправьте `contents` в `generateContent` и читайте `candidates`
Формат	Формат Gemini Developer API, версия `v1beta`, ID модели в пути
Модели	Те, у которых в столбце Endpoints каталога моделей указан Gemini
Модель в примерах	`gemini-3.8-flash`
Медиа на входе	Изображения, PDF, аудио и видео MP4; про видео — в разделе API понимания видео

Эндпоинт:

POST https://api.laozhang.ai/v1beta/models/{model}:generateContent

Если приложение уже использует messages в стиле OpenAI, вызывайте модели Gemini через протокол OpenAI.

Ключ и выбор модели

Создайте API-ключ для моделей в разделе Управление токенами, выбрав режим оплаты «сначала по использованию» (в консоли — 按量优先, рекомендуется) или «оплата по использованию» (按量计费), и сохраните его в переменной окружения:

export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"

Этот формат принимают модели, у которых в столбце Endpoints каталога моделей указан Gemini. В примерах используется gemini-3.8-flash; убедитесь, что группа вашего токена может её вызывать, на странице Модели и цены. Нативные запросы Gemini принимают аутентификацию как через Authorization: Bearer, так и через x-goog-api-key. Google Gen AI SDK подставляет заголовок с ключом автоматически.

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

cURL
Python

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Ответь только одним словом: connected"}]
    }]
  }'

Чтобы использовать заголовок ключа Google, замените заголовок Authorization на:

-H "x-goog-api-key: $LAOZHANG_API_KEY"

Установите SDK:

python -m pip install google-genai

Задайте в base_url корень хоста, а в api_version — v1beta. SDK сам добавит версию и путь модели; таймаут в нём указывается в миллисекундах.

import os
from google import genai

client = genai.Client(
    api_key=os.environ["LAOZHANG_API_KEY"],
    http_options={
        "base_url": "https://api.laozhang.ai",
        "api_version": "v1beta",
        "timeout": 120_000,
    },
)
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Ответь только одним словом: connected",
)
print(response.text)

В ответе должно быть connected. Не добавляйте /v1 к базовому URL Google SDK и не используйте для этого эндпоинта путь Vertex AI с проектом, регионом и издателем.

Потоковый ответ

Чтобы получать ответ потоком, отправьте то же тело на https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse: каждое server-sent event содержит часть ответа с той же структурой candidates.

Структура запроса

В contents лежат сообщения по порядку. У каждого сообщения есть role и одна или несколько частей parts.

Поле	Значение
`contents`	Обязательный массив сообщений диалога.
`role`	`user` для ввода пользователя; `model` для ответа модели.
`parts`	Содержимое сообщения: текст и медиа, которые принимает модель.
`text`	Текстовая часть.
`inlineData`	Встроенное медиа с `mimeType` и данными `data` в Base64.
`fileData`	Медиа, на которое указывает ссылка: `fileUri` и `mimeType`.
`systemInstruction`	Инструкции, передаваемые отдельно от диалога.
`generationConfig`	Настройки генерации, зависящие от модели.

REST JSON использует camelCase, например inlineData и mimeType. В свойствах Python SDK имена другие, например inline_data и mime_type; используйте написание, соответствующее интерфейсу, который вызываете. Необязательные настройки и поддержка медиа зависят от модели.

Передача изображения

Для модели, принимающей изображения, например gemini-3.8-flash, поместите текстовую часть и часть inlineData в одно сообщение. Этот код читает локальный файл input.png и записывает JSON-запрос.

import base64
import json
from pathlib import Path

request = {
    "contents": [{
        "role": "user",
        "parts": [
            {"text": "Опиши объекты на этом изображении."},
            {"inlineData": {
                "mimeType": "image/png",
                "data": base64.b64encode(Path("input.png").read_bytes()).decode("ascii"),
            }},
        ],
    }],
}
Path("gemini-request.json").write_text(json.dumps(request), encoding="utf-8")

Отправьте этот файл как тело запроса:

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @gemini-request.json

MIME-тип должен совпадать с реальным форматом изображения. В data передаётся чистый Base64 без префикса data:image/png;base64,. Описание изображения и его генерация — разные операции. Как создавать и редактировать изображения моделями Gemini, читайте в обзоре API Nano Banana. Как отправлять изображения модели с поддержкой зрения в формате OpenAI, описано в разделе API понимания изображений.

Передача PDF или аудиофайла

PDF и аудио передаются в inlineData так же, как изображения; меняется только mimeType:

Файл	`mimeType`	Что может модель
PDF	`application/pdf`	Прочитать все страницы и ответить на вопросы, охватывающие несколько страниц
Аудио MP3	`audio/mp3`	Расшифровать речь на английском или китайском, кратко пересказать её или ответить на вопросы о ней

Пример читает invoice.pdf из текущей папки. Для аудио замените имя файла на audio.mp3, укажите mimeType равным audio/mp3 и поменяйте вопрос.

cURL
Python SDK

Запишите тело запроса:

import base64
import json
from pathlib import Path

request = {
    "contents": [{
        "role": "user",
        "parts": [
            {"inlineData": {
                "mimeType": "application/pdf",
                "data": base64.b64encode(Path("invoice.pdf").read_bytes()).decode("ascii"),
            }},
            {"text": "Каковы номер счёта, сумма к оплате и срок оплаты?"},
        ],
    }],
}
Path("gemini-file-request.json").write_text(json.dumps(request), encoding="utf-8")

Затем отправьте его:

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @gemini-file-request.json

import os
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["LAOZHANG_API_KEY"],
    http_options={
        "base_url": "https://api.laozhang.ai",
        "api_version": "v1beta",
        "timeout": 120_000,
    },
)
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_bytes(
            data=Path("audio.mp3").read_bytes(),
            mime_type="audio/mp3",
        ),
        "Расшифруй это аудио, а затем перескажи его одним предложением.",
    ],
)
print(response.text)

Аудио оплачивается за токены и отображается как AUDIO в usageMetadata.promptTokensDetails. Если нужна только расшифровка без дальнейших рассуждений, подойдёт и API транскрипции аудио.

Анализ видео

Видео MP4 тоже передаётся в inlineData, а mimeType задаётся как video/mp4. Для публичной ссылки или публичного видео на YouTube используйте fileData. Модель читает кадры и звуковую дорожку вместе:

{"inlineData": {"mimeType": "video/mp4", "data": "<BASE64_DATA>"}}

{"fileData": {"fileUri": "https://www.youtube.com/watch?v=9hE5-98ZeCg", "mimeType": "video/mp4"}}

Полные примеры и типовые задачи — на странице API понимания видео:

Отправка локального видео и анализ видео по ссылке.
Разбиение видео на главы с таймкодами и возврат структурированного JSON.
Выбор фрагмента или изменение частоты кадров через videoMetadata.
Сравнение видео, потоковый ответ и вызов через OpenAI SDK.

Чтение ответа

Текстовый ответ выглядит так (остальные метаданные опущены):

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "connected"}]
    },
    "finishReason": "STOP"
  }]
}

Читайте текст из content.parts кандидата: частей может быть несколько. Хелпер response.text в Python SDK собирает текст за вас. Если приложению нужны медиа, вызовы инструментов или история диалога, сохраняйте содержимое кандидата целиком. Если в ответе нет текста, посмотрите promptFeedback, finishReason и нетекстовые части. Блокировка содержимого, лимит вывода и вызов инструмента обрабатываются иначе, чем сетевая ошибка. Данные об использовании, если они есть, находятся в usageMetadata; списания по аккаунту видны в журнале вызовов.

Продолжение диалога

Отправьте в contents прежнее сообщение пользователя, полный ответ модели и новое сообщение пользователя. Для ответов модели в Gemini используется роль model, а не assistant. Продолжая работу с моделью, сохраняйте возвращённые части. Если модель возвращает thoughtSignature, передайте подпись обратно без изменений вместе с её частью. Для моделей с вызовом инструментов каждому functionCall сопоставляйте подходящий functionResponse: краткий текстовый пересказ не заменяет структуру результата инструмента. Форматы этих сообщений описаны в справочнике generateContent от Google.

Устранение неполадок

401: проверьте API-ключ и заголовок аутентификации. Используйте API-ключ для моделей, а не AccessToken для управления аккаунтом.
404 или модель не найдена: проверьте v1beta, точный ID модели и доступ группы токена к нативному Gemini.
400: проверьте contents, parts, роли сообщений, кодировку медиа и необязательные настройки, названные в ошибке.
Ответ без текста: посмотрите кандидатов, причины завершения, данные о блокировке и нетекстовое содержимое.
400 с «Cannot fetch content from the provided URL»: изображение или видео по ссылке нельзя скачать напрямую. Используйте публичную прямую ссылку без авторизации, не закрытую в robots.txt сайта, либо передайте файл через inlineData.
413: тело запроса слишком большое. Держите весь запрос в пределах 20 МБ, а большие файлы передавайте по ссылке через fileData.
Загрузка файла возвращает веб-страницу или 404: File API недоступен. Используйте inlineData или ссылку в fileData.
cURL работает, а SDK нет: проверьте базовый URL и версию API в SDK. В итоговом URL /v1beta/models/ должно встречаться только один раз.

При таймауте или временной ошибке сервера посмотрите журнал вызовов, прежде чем повторять запрос. Обращаясь в поддержку, укажите время запроса, модель и текст ошибки без секретных данных.

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

Сколько стоит Gemini API и нужен ли аккаунт Google?

Аккаунт Google и ключ AI Studio не нужны: достаточно ключа LaoZhang API, а текстовые модели Gemini оплачиваются за токены с предоплаченного баланса. Публичные цены на 14 октября 2026 года, за 1M токенов:

gemini-4-argon: $2 за вход, $10 за выход
gemini-3.8-flash: $0.75 за вход, $3.75 за выход
gemini-2.5-flash: $0.3 за вход, $2.4 за выход

Другие модели Gemini и ступени длинного контекста — в каталоге моделей и цен, а сумма за каждый запрос — в журнале вызовов. Платформа не ограничивает параллельность и не замедляет запросы; ошибка 429 приходит из-за ёмкости upstream, см. параллельные запросы и 429.

Какие медиа можно отправить через эндпоинт, совместимый с OpenAI?

С моделями Gemini на /v1/chat/completions:

Изображения: передайте URL или data URL в Base64 в image_url; см. API понимания изображений.
Видео: передайте data URL в Base64 в video_url; см. раздел о вызове через OpenAI SDK в API понимания видео.
PDF в частях file и аудио в частях input_audio отбрасываются. Запрос всё равно возвращает 200, и модель может ответить, не увидев файл. Отправляйте их через inlineData, как описано на этой странице.

Можно ли использовать Responses API с моделями Gemini?

Нет. Модели Gemini на /v1/responses возвращают 400. В OpenAI SDK вызывайте Chat Completions; для PDF, аудио, видео и ссылок на видео используйте нативный эндпоинт с этой страницы.

Поддерживается ли Google File API?

Нет. Недоступны:

Эндпоинт загрузки /upload/v1beta/files
Ссылки вида files/...
Метод SDK client.files.upload()

Локальные файлы отправляйте через inlineData, а публичные видео — по ссылке в fileData.

Как оплачиваются мультимедийные входные данные?

Текстовые модели Gemini оплачиваются за токены. Изображения, PDF, аудио и видео преобразуются во входные токены, а usageMetadata.promptTokensDetails перечисляет их по типам, например IMAGE, AUDIO и VIDEO. Цены указаны в каталоге моделей, а сумма за каждый запрос — в журнале вызовов.

Можно ли вызвать Veo или Nano Banana Pro нативно?

Nano Banana Pro: gemini-3-pro-image работает с нативным generateContent; см. Nano Banana Pro.
Veo: на 28 сентября 2026 года Veo нет в публичном каталоге моделей, а нативные запросы predictLongRunning возвращают ошибку об отсутствии доступного канала. Для генерации видео используйте Wan 2.7 или Seedance 2.0.

На чём работают модели Google: AI Studio или Vertex AI?

На AI Studio. LaoZhang API вызывает текстовые модели Gemini и модели изображений Nano Banana через Gemini API от Google (AI Studio), а не через Vertex AI. Поэтому:

ID моделей, даты отключения и политики безопасности соответствуют документации Gemini API, например странице об устаревании моделей Google.
Запросы идут по пути v1beta в стиле AI Studio, без проекта и региона Vertex.
Если подозреваете сбой на стороне upstream, проверьте инциденты Gemini API на странице статуса AI Studio.

Начало работы

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

API генерации видео

API для текста

Gemini API через generateContent: SDK, изображения, PDF, видео

Ключ и выбор модели

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

Потоковый ответ

Структура запроса

Передача изображения

Передача PDF или аудиофайла

Анализ видео

Чтение ответа

Продолжение диалога

Устранение неполадок

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

Сколько стоит Gemini API и нужен ли аккаунт Google?

Какие медиа можно отправить через эндпоинт, совместимый с OpenAI?

Можно ли использовать Responses API с моделями Gemini?

Поддерживается ли Google File API?

Как оплачиваются мультимедийные входные данные?

Можно ли вызвать Veo или Nano Banana Pro нативно?

На чём работают модели Google: AI Studio или Vertex AI?

Связанные материалы

​Ключ и выбор модели

​Генерация текста

​Потоковый ответ

​Структура запроса

​Передача изображения

​Передача PDF или аудиофайла

​Анализ видео

​Чтение ответа

​Продолжение диалога

​Устранение неполадок

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

​Сколько стоит Gemini API и нужен ли аккаунт Google?

​Какие медиа можно отправить через эндпоинт, совместимый с OpenAI?

​Можно ли использовать Responses API с моделями Gemini?

​Поддерживается ли Google File API?

​Как оплачиваются мультимедийные входные данные?

​Можно ли вызвать Veo или Nano Banana Pro нативно?

​На чём работают модели Google: AI Studio или Vertex AI?

​Связанные материалы

Ключ и выбор модели

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

Потоковый ответ

Структура запроса

Передача изображения

Передача PDF или аудиофайла

Анализ видео

Чтение ответа

Продолжение диалога

Устранение неполадок

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

Сколько стоит Gemini API и нужен ли аккаунт Google?

Какие медиа можно отправить через эндпоинт, совместимый с OpenAI?

Можно ли использовать Responses API с моделями Gemini?

Поддерживается ли Google File API?

Как оплачиваются мультимедийные входные данные?

Можно ли вызвать Veo или Nano Banana Pro нативно?

На чём работают модели Google: AI Studio или Vertex AI?

Связанные материалы