> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Как вызвать нативный эндпоинт Gemini generateContent через LaoZhang API из cURL или Python SDK и отправить текст, изображения, PDF, аудио или видео MP4.

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

| Параметр | Значение |
| - | - |
| Запрос и ответ | Отправьте `contents` в `generateContent` и читайте `candidates` |
| Формат | Формат Gemini Developer API, версия `v1beta`, ID модели в пути |
| Модели | Те, у которых в столбце **Endpoints** [каталога моделей](https://docs.laozhang.ai/ru/models.md) указан Gemini |
| Модель в примерах | `gemini-3.8-flash` |
| Медиа на входе | Изображения, PDF, аудио и видео MP4; про видео — в разделе [API понимания видео](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md) |

Эндпоинт:

```text theme={null}
POST https://api.laozhang.ai/v1beta/models/{model}:generateContent
```

Если приложение уже использует `messages` в стиле OpenAI, вызывайте модели Gemini через [протокол OpenAI](https://docs.laozhang.ai/ru/api-reference/chat-completions.md).

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

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

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
```

Этот формат принимают модели, у которых в столбце **Endpoints** [каталога моделей](https://docs.laozhang.ai/ru/models.md) указан Gemini. В примерах используется `gemini-3.8-flash`; убедитесь, что группа вашего токена может её вызывать, на странице [Модели и цены](https://api.laozhang.ai/account/pricing).

Нативные запросы Gemini принимают аутентификацию как через `Authorization: Bearer`, так и через `x-goog-api-key`. Google Gen AI SDK подставляет заголовок с ключом автоматически.

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

> [tab] cURL
>
> ```bash theme={null}
> 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` на:
>
> ```bash theme={null}
> -H "x-goog-api-key: $LAOZHANG_API_KEY"
> ```

> [tab] Python
>
> Установите SDK:
>
> ```bash theme={null}
> python -m pip install google-genai
> ```
>
> Задайте в `base_url` корень хоста, а в `api_version` — `v1beta`. SDK сам добавит версию и путь модели; таймаут в нём указывается в миллисекундах.
>
> ```python theme={null}
> 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-запрос.

```python theme={null}
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")
```

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

```bash theme={null}
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](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-image.md). Как отправлять изображения модели с поддержкой зрения в формате OpenAI, описано в разделе [API понимания изображений](https://docs.laozhang.ai/en/api-capabilities/vision-understanding.md).

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

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

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

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

> [tab] cURL
>
> Запишите тело запроса:
>
> ```python theme={null}
> 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")
> ```
>
> Затем отправьте его:
>
> ```bash theme={null}
> 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
> ```

> [tab] Python SDK
>
> ```python theme={null}
> 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 транскрипции аудио](https://docs.laozhang.ai/en/api-capabilities/audio-transcription.md).

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

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

```json theme={null}
{"inlineData": {"mimeType": "video/mp4", "data": "<BASE64_DATA>"}}
```

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

Полные примеры и типовые задачи — на странице [API понимания видео](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md):

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

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

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

```json theme={null}
{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "connected"}]
    },
    "finishReason": "STOP"
  }]
}
```

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

Если в ответе нет текста, посмотрите `promptFeedback`, `finishReason` и нетекстовые части. Блокировка содержимого, лимит вывода и вызов инструмента обрабатываются иначе, чем сетевая ошибка. Данные об использовании, если они есть, находятся в `usageMetadata`; списания по аккаунту видны в [журнале вызовов](https://docs.laozhang.ai/en/faq/call-logs.md).

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

Отправьте в `contents` прежнее сообщение пользователя, полный ответ модели и новое сообщение пользователя. Для ответов модели в Gemini используется роль `model`, а не `assistant`.

Продолжая работу с моделью, сохраняйте возвращённые части. Если модель возвращает `thoughtSignature`, передайте подпись обратно без изменений вместе с её частью.

Для моделей с вызовом инструментов каждому `functionCall` сопоставляйте подходящий `functionResponse`: краткий текстовый пересказ не заменяет структуру результата инструмента. Форматы этих сообщений описаны в [справочнике generateContent](https://ai.google.dev/api/generate-content) от 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/` должно встречаться только один раз.

При таймауте или временной ошибке сервера посмотрите [журнал вызовов](https://api.laozhang.ai/log), прежде чем повторять запрос. Обращаясь в поддержку, укажите время запроса, модель и текст ошибки без секретных данных.

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

### Сколько стоит 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 и ступени длинного контекста — в [каталоге моделей и цен](https://docs.laozhang.ai/ru/models.md), а сумма за каждый запрос — в [журнале вызовов](https://docs.laozhang.ai/en/faq/call-logs.md). Платформа не ограничивает параллельность и не замедляет запросы; ошибка `429` приходит из-за ёмкости upstream, см. [параллельные запросы и 429](https://docs.laozhang.ai/ru/faq/api-concurrency.md).

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

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

* Изображения: передайте URL или data URL в Base64 в `image_url`; см. [API понимания изображений](https://docs.laozhang.ai/en/api-capabilities/vision-understanding.md).
* Видео: передайте data URL в Base64 в `video_url`; см. раздел о вызове через OpenAI SDK в [API понимания видео](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md).
* 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`. Цены указаны в [каталоге моделей](https://docs.laozhang.ai/ru/models.md), а сумма за каждый запрос — в [журнале вызовов](https://docs.laozhang.ai/en/faq/call-logs.md).

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

* **Nano Banana Pro:** `gemini-3-pro-image` работает с нативным `generateContent`; см. [Nano Banana Pro](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-pro-image.md).
* **Veo:** на 28 сентября 2026 года Veo нет в публичном каталоге моделей, а нативные запросы `predictLongRunning` возвращают ошибку об отсутствии доступного канала. Для генерации видео используйте [Wan 2.7](https://docs.laozhang.ai/ru/api-capabilities/wan-video-generation.md) или [Seedance 2.0](https://docs.laozhang.ai/ru/api-capabilities/seedance2-video-generation.md).

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

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

* ID моделей, даты отключения и политики безопасности соответствуют [документации Gemini API](https://ai.google.dev/gemini-api/docs), например [странице об устаревании моделей](https://ai.google.dev/gemini-api/docs/deprecations) Google.
* Запросы идут по пути `v1beta` в стиле AI Studio, без проекта и региона Vertex.
* Если подозреваете сбой на стороне upstream, проверьте инциденты Gemini API на [странице статуса AI Studio](https://aistudio.google.com/status).

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

* [API понимания видео](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md)
* [Справочник Google generateContent](https://ai.google.dev/api/generate-content)
* [Google Gen AI Python SDK](https://googleapis.github.io/python-genai/)
* [Протокол OpenAI: Chat Completions](https://docs.laozhang.ai/ru/api-reference/chat-completions.md)
* [Каталог моделей и цены](https://docs.laozhang.ai/ru/models.md)
* [Доступ к моделям и права](https://docs.laozhang.ai/en/faq/model-availability.md)
* [Руководство по подключению](https://docs.laozhang.ai/ru/api-manual.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.