Обзор

API Google Gemini структурно отличается от OpenAI. Meridian выполняет обширное преобразование:

• Переименование ролей — "assistant" → "model", system-сообщения интегрируются в основной поток.
• Группировка сообщений — подряд идущие tool-ответы сливаются в одно user-сообщение.
• Переименование параметров — например, max_completion_tokens → maxOutputTokens, stop → stopSequences.
• Обработка function calls — сохранение tool call ID и поддержка thought signature.
• Модальность контента — поддержка текста, изображений, видео, выполнения кода и thought-контента.
• Thinking / Reasoning — конфигурация thinking маппится в структуру reasoning Meridian.

Поддерживаемые операции

Аутентификация

Gemini поддерживает аутентификацию по API-ключу в дополнение к OAuth2 Bearer token. Реализация выбирает подходящий метод в зависимости от типа эндпоинта.

Аутентификация по API-ключу

API-ключ передаётся одним из двух способов:

1. Через заголовок (стандартные эндпоинты Gemini):

   • Формат: заголовок x-goog-api-key: YOUR_API_KEY.
   • Используется для стандартных эндпоинтов Gemini (например, /v1beta/models/{model}:generateContent).

2. Через query-параметр (Imagen и кастомные эндпоинты):

   • Формат: ?key=YOUR_API_KEY в URL запроса.
   • Используется для моделей Imagen и кастомных эндпоинтов.
   • Пример: https://generativelanguage.googleapis.com/v1beta/models/imagen-4.0-generate-001:predict?key=YOUR_API_KEY.

Meridian автоматически выбирает подходящий метод аутентификации по типу эндпоинта.

1. Chat Completions

Параметры запроса

Маппинг параметров

Игнорируемые параметры

Следующие параметры тихо игнорируются: logit_bias, logprobs, top_logprobs, parallel_tool_calls, service_tier.

Extra-параметры

Используйте extra_params или передавайте напрямую в теле запроса для специфичных для Gemini полей:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini/gemini-2.0-flash",
    "messages": [{"role": "user", "content": "Hello"}],
    "top_k": 40,
    "stop_sequences": ["###"]
  }'

Reasoning / Thinking

Документация: см. Reasoning.

Маппинг параметров

• reasoning.effort → thinkingConfig.thinkingLevel ("low" → LOW, "high" → HIGH).
• reasoning.max_tokens → thinkingConfig.thinkingBudget (бюджет токенов на thinking).
• Наличие параметра reasoning включает thinkingConfig.includeThoughts = true.

Поддерживаемые уровни thinking

• "low" / "minimal" → LOW.
• "medium" / "high" → HIGH.
• null или не задано → определяется по max_tokens: -1 (динамический), 0 (отключено) или конкретный бюджет.

Пример

// Запрос
{"reasoning": {"effort": "high", "max_tokens": 10000}}

// Преобразование Gemini
{"thinkingConfig": {"includeThoughts": true, "thinkingLevel": "HIGH", "thinkingBudget": 10000}}

Конвертация сообщений

Критичные нюансы

• Переименование ролей: "assistant" → "model", "system" → часть потока user/model.
• Подряд идущие tool-ответы: tool-сообщения сливаются в одно user-сообщение с function response parts.
• Уплощение контента: multi-part контент в одном сообщении сохраняется как массив parts.

Конвертация изображений

• URL-изображения: {type: "image_url", image_url: {url: "..."}} → {type: "image", source: {type: "url", url: "..."}}.
• Base64-изображения: data URL → {type: "image", source: {type: "base64", media_type: "image/png", ...}}.
• Видео-контент: сохраняется с метаданными (fps, start/end offset).

Tool Conversion

Определения tools реструктурируются:

• function.name → functionDeclarations.name (сохраняется).
• function.parameters → functionDeclarations.parameters (формат Schema).
• function.description → functionDeclarations.description.
• function.strict → отбрасывается (Gemini не поддерживает).

Маппинг tool_choice

Конвертация ответа

Маппинг полей

• finishReason → finish_reason:
  • STOP → stop;
  • MAX_TOKENS → length;
  • SAFETY, RECITATION, LANGUAGE, BLOCKLIST, PROHIBITED_CONTENT, SPII, IMAGE_SAFETY → content_filter;
  • MALFORMED_FUNCTION_CALL, UNEXPECTED_TOOL_CALL → tool_calls.
• candidates[0].content.parts[0].text → choices[0].message.content (если единственный text-блок).
• candidates[0].content.parts[].functionCall → choices[0].message.tool_calls.
• promptTokenCount → usage.prompt_tokens.
• candidatesTokenCount → usage.completion_tokens.
• totalTokenCount → usage.total_tokens.
• cachedContentTokenCount → usage.prompt_tokens_details.cached_tokens.
• thoughtsTokenCount → usage.completion_tokens_details.reasoning_tokens.
• Thought-контент (text parts с thought: true) → поле reasoning в stream-дельтах.
• Function call args (map) → JSON-строка arguments.

Streaming

Структура событий:

• Streaming-ответы содержат дельты в delta.content (текст), delta.reasoning (thoughts), delta.toolCalls (function calls).
• Function-ответы появляются как text content в дельте.
• finish_reason присутствует только в финальном чанке.
• Usage-метаданные включаются только в финальный чанк.

2. Responses API

Responses API использует тот же базовый эндпоинт /generateContent, но конвертирует между форматом OpenAI Responses и форматом Gemini Messages.

Параметры запроса

Маппинг параметров

Extra-параметры

Используйте extra_params или передавайте напрямую в теле запроса:

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini/gemini-2.0-flash",
    "input": "Hello, how are you?",
    "instructions": "You are a helpful assistant.",
    "top_k": 40
  }'

Input и Instructions

• Input: строка оборачивается как user-сообщение, массив конвертируется в сообщения.
• Instructions: становится system instruction (одиночный text-блок).

Поддержка tools

Поддерживаемые типы: function, computer_use_preview, web_search, mcp.

Конвертации tools те же, что в Chat Completions, с дополнениями:

• Computer-tools автоматически конфигурируются (если заданы в запросе Meridian).
• Function-based tools всегда включены.

Конвертация ответа

• finishReason → status: STOP/MAX_TOKENS/прочее → completed, SAFETY → incomplete.
• Конвертация output items:
  • Text parts → поле message;
  • Function calls → поле function_call;
  • Thought-контент → поле reasoning.
• Usage-поля сохраняются, cache-токены маппятся в *_tokens_details.cached_tokens.

Streaming

Структура событий аналогична Chat Completions streaming:

• content_part.added эмитится для text и reasoning parts.
• Идентификаторы элементов формируются как msg_{responseID}_item_{outputIndex}.

3. Speech (Text-to-Speech)

Синтез речи использует базовый эндпоинт chat generation с audio response modality.

Параметры запроса

Конфигурация голоса

Single Voice:

{
  "generationConfig": {
    "responseModalities": ["AUDIO"],
    "speechConfig": {
      "voiceConfig": {
        "prebuiltVoiceConfig": {
          "voiceName": "Chant-Female"
        }
      }
    }
  }
}

Multi-Speaker:

{
  "generationConfig": {
    "responseModalities": ["AUDIO"],
    "speechConfig": {
      "multiSpeakerVoiceConfig": {
        "speakerVoiceConfigs": [
          {
            "speaker": "Character A",
            "voiceConfig": {
              "prebuiltVoiceConfig": {
                "voiceName": "Chant-Female"
              }
            }
          }
        ]
      }
    }
  }
}

Конвертация ответа

• Аудио-данные извлекаются из candidates[0].content.parts[].inlineData.
• Конвертация формата: Gemini возвращает PCM-аудио (s16le, 24 kHz, mono).
• Авто-конвертация: PCM → WAV при response_format: "wav" (по умолчанию).
• Сырое аудио возвращается, если response_format опущен или пуст.

Поддерживаемые голоса

Типовые голоса Gemini:

• Chant-Female — женский голос;
• Chant-Male — мужской голос;
• остальные голоса зависят от возможностей модели.

Полный список поддерживаемых голосов смотрите в документации модели.

4. Transcriptions (Speech-to-Text)

Transcriptions реализованы как chat completions с audio content и текстовым промптом.

Параметры запроса

Обработка audio input

Аудио передаётся как inline data с авто-определением MIME-типа:

{
  "contents": [
    {
      "parts": [
        {
          "text": "<prompt text>"
        },
        {
          "inlineData": {
            "mimeType": "audio/wav",
            "data": "<base64-encoded-audio>"
          }
        }
      ]
    }
  ]
}

Extra-параметры

Можно настроить safety settings и кэширование:

curl -X POST http://localhost:8080/v1/audio/transcriptions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini/gemini-2.0-flash",
    "file": "<binary-audio-data>",
    "prompt": "Transcribe this audio in the original language."
  }'

Конвертация ответа

• Транскрибированный текст извлекается из candidates[0].content.parts[].text.
• task устанавливается в "transcribe".
• Usage-метаданные маппятся:
  • promptTokenCount → input_tokens;
  • candidatesTokenCount → output_tokens;
  • totalTokenCount → total_tokens.

5. Embeddings

Параметры запроса:

• input → requests[0].content.parts[0].text (одиночный текст для массивов склеивается через пробел);
• dimensions → outputDimensionality;
• task type и title передаются через extra_params.

Маппинг ответа:

• embeddings[].values → массив embedding в Meridian;
• metadata.billableCharacterCount → usage prompt tokens (fallback);
• счётчики токенов извлекаются из usage metadata.

6. Batch API

Форматы запроса: массив inline-запросов или файловый вход.

Пагинация: токен-based — pageToken.

Эндпоинты:

• POST /v1beta/batchJobs — создание;
• GET /v1beta/batchJobs?pageSize={limit}&pageToken={token} — список;
• GET /v1beta/batchJobs/{batch_id} — получение;
• POST /v1beta/batchJobs/{batch_id}:cancel — отмена.

Структура ответа:

• Маппинг статусов: BATCH_STATE_PENDING/BATCH_STATE_RUNNING → in_progress, BATCH_STATE_SUCCEEDED → completed, BATCH_STATE_FAILED → failed, BATCH_STATE_CANCELLING → cancelling, BATCH_STATE_CANCELLED → cancelled, BATCH_STATE_EXPIRED → expired.
• Inline-ответы: массив в dest.inlinedResponses.
• File-ответы: JSONL-файл в dest.fileName.

Замечание: метки RFC3339 конвертируются в Unix timestamp.

7. Files API

Загрузка: multipart/form-data с полями file (binary) и filename (опционально).

Маппинг полей:

• name → id;
• displayName → filename;
• sizeBytes → size_bytes;
• mimeType → content_type;
• createTime (RFC3339) → Unix timestamp.

Эндпоинты:

• POST /upload/storage/v1beta/files — загрузка;
• GET /v1beta/files?limit={limit}&pageToken={token} (cursor-пагинация);
• GET /v1beta/files/{file_id} — метаданные;
• DELETE /v1beta/files/{file_id} — удаление;
• GET /v1beta/files/{file_id}/content — скачивание.

8. Image Generation

Gemini поддерживает два формата генерации изображений в зависимости от модели:

1. Стандартный формат Gemini: использует эндпоинт /v1beta/models/{model}:generateContent.
2. Формат Imagen: использует эндпоинт /v1beta/models/{model}:predict для моделей Imagen (определяется автоматически).

Маппинг параметров

Extra-параметры

Используйте extra_params или передавайте напрямую в теле запроса для специфичных для Gemini полей:

curl -X POST http://localhost:8080/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini/imagen-4.0-generate-001",
    "prompt": "A sunset over the mountains",
    "size": "1024x1024",
    "n": 2,
    "output_format": "png"
  }'

Конвертация запроса

Стандартный формат Gemini

• Маппинг модели: bifrostReq.Model → req.Model, bifrostReq.Input.Prompt → req.Contents[0].Parts[0].Text.
• Response modality: внутренне задаётся generationConfig.responseModalities = ["IMAGE"] для индикации генерации изображения.
• Количество изображений: n → generationConfig.candidateCount.
• Extra-параметры: safetySettings, cachedContent и labels маппятся напрямую.

Формат Imagen

• Prompt: bifrostReq.Prompt → req.Instances[0].Prompt.
• Количество изображений: n → req.Parameters.SampleCount.
• Конвертация size: size (формат WxH) преобразуется в:
  • imageSize: "1k" (если размеры ≤ 1024), "2k" (если ≤ 2048). Размеры больше "2k" моделями Imagen не поддерживаются.
  • aspectRatio: "1:1", "3:4", "4:3", "9:16" или "16:9" (по соотношению width/height).
• Output Format: output_format ("png", "jpeg") → parameters.outputOptions.mimeType ("image/png", "image/jpeg").
• Seed и Negative Prompt: передаются напрямую в seed и parameters.negativePrompt.
• Extra-параметры: personGeneration, language, enhancePrompt, safetySettings маппятся в parameters.

Конвертация ответа

Стандартный формат Gemini

• Данные изображения: извлекаются InlineData из candidates[0].content.parts[] с MIME-типом image/*.
• Output Format: MIME-тип (image/png, image/jpeg, image/webp) конвертируется в расширение файла (png, jpeg, webp).
• Usage: usage токенов извлекается из usageMetadata.
• Несколько изображений: каждая image-part становится записью ImageData в массиве ответа.

Формат Imagen

• Данные изображения: каждый prediction в response.predictions[] → ImageData с b64_json из bytesBase64Encoded.
• Output Format: prediction.mimeType → расширение файла в поле outputFormat (Imagen не поддерживает webp).
• Index: каждому prediction присваивается index (0, 1, 2, ...) в массиве ответа.

Конвертация size

Для формата Imagen size конвертируется между форматами:

Поддерживаемые размеры изображений: "1k" (≤1024), "2k" (≤2048).

Поддерживаемые aspect ratio: "1:1", "3:4", "4:3", "9:16", "16:9".

Выбор эндпоинта

Провайдер автоматически выбирает эндпоинт по имени модели:

• Imagen-модели (определяются через schemas.IsImagenModel()): эндпоинт /v1beta/models/{model}:predict.
• Другие модели: эндпоинт /v1beta/models/{model}:generateContent с image response modality.

Streaming

Streaming генерации изображений в Gemini не поддерживается.

9. Image Edit

Gemini поддерживает редактирование изображений через два разных API в зависимости от модели:

1. Стандартный формат Gemini: эндпоинт /v1beta/models/{model}:generateContent (для моделей Gemini).
2. Формат Imagen: эндпоинт /v1beta/models/{model}:predict (для моделей Imagen, определяется автоматически).

Параметры запроса:

Конвертация запроса

Стандартный формат Gemini (не-Imagen модели)

• Model и Prompt: bifrostReq.Model → req.Model, bifrostReq.Input.Prompt → req.Contents[0].Parts[0].Text.
• Изображения: каждое изображение в bifrostReq.Input.Images конвертируется в Part с:
  • определением MIME-типа (image/jpeg, image/webp, image/png) с fallback на image/png;
  • base64-кодирование: image.Image → Part.InlineData.Data (base64-строка);
  • MIME-тип: Part.InlineData.MIMEType.
• Response Modality: GenerationConfig.ResponseModalities задаётся как [ModalityImage] для индикации генерации изображения.
• Extra-параметры: извлекаются из ExtraParams:
  • safetySettings / safety_settings → SafetySettings;
  • cachedContent / cached_content → CachedContent;
  • labels → Labels (map[string]string).

Формат Imagen (модели Imagen)

• Reference Images: каждое изображение в bifrostReq.Input.Images конвертируется в ReferenceImage с:
  • ReferenceType: "REFERENCE_TYPE_RAW";
  • ReferenceID: последовательные ID начиная с 1;
  • ReferenceImage.BytesBase64Encoded: base64-кодированные данные изображения.
• Конфигурация маски: если задан Params.Mask или maskMode:
  • дефолтный maskMode: "MASK_MODE_USER_PROVIDED", когда есть данные маски;
  • maskMode можно переопределить через ExtraParams["maskMode"];
  • dilation извлекается из ExtraParams["dilation"] (валидируется диапазоном [0, 1]);
  • maskClasses извлекается из ExtraParams["maskClasses"] (для MASK_MODE_SEMANTIC);
  • mask-изображение (если задано) кодируется в base64 и добавляется как ReferenceType: "REFERENCE_TYPE_MASK".
• Маппинг Edit Mode: Params.Type маппится в EditMode:
  • "inpainting" → "EDIT_MODE_INPAINT_INSERTION";
  • "outpainting" → "EDIT_MODE_OUTPAINT";
  • "inpaint_removal" → "EDIT_MODE_INPAINT_REMOVAL";
  • "bgswap" → "EDIT_MODE_BGSWAP";
  • если Type не задан, editMode можно задать напрямую через ExtraParams["editMode"].
• Параметры:
  • n → Parameters.SampleCount;
  • output_format → Parameters.OutputOptions.MimeType (конвертация: "png" → "image/png" и т.д.);
  • output_compression → Parameters.OutputOptions.CompressionQuality;
  • seed (через ExtraParams["seed"]) → Parameters.Seed;
  • negativePrompt (через ExtraParams["negativePrompt"]) → Parameters.NegativePrompt;
  • guidanceScale (через ExtraParams["guidanceScale"]) → Parameters.GuidanceScale;
  • baseSteps (через ExtraParams["baseSteps"]) → Parameters.BaseSteps;
  • дополнительные параметры Imagen: addWatermark, includeRaiReason, includeSafetyAttributes, personGeneration, safetySetting, language, storageUri.

Конвертация ответа

• Стандартный формат Gemini: та же конвертация, что и у image generation (см. раздел Image Generation).
• Формат Imagen: та же конвертация, что и у Imagen image generation (см. раздел Image Generation).

Выбор эндпоинта

Провайдер автоматически выбирает эндпоинт по имени модели:

• Imagen-модели (определяются через schemas.IsImagenModel()): эндпоинт /v1beta/models/{model}:predict.
• Другие модели: эндпоинт /v1beta/models/{model}:generateContent с image response modality.

Streaming

Streaming для image edit в Gemini не поддерживается.

Image Variation

Image variation в Gemini не поддерживается.

10. List Models

Запрос: GET /v1beta/models?pageSize={limit}&pageToken={token} (без тела).

Маппинг полей:

• name (с удалением префикса "models/") → id (с добавлением префикса "gemini/");
• displayName → name;
• description → description;
• inputTokenLimit → max_input_tokens;
• outputTokenLimit → max_output_tokens;
• Длина контекста = inputTokenLimit + outputTokenLimit.

Пагинация: токен-based — nextPageToken.

11. Video Generation

Generate (POST /v1/videos)

Запросы используют JSON body (application/json).

Параметры запроса:

Extra Params (любое нераспознанное JSON-поле пробрасывается как extra_params):

Ответ: BifrostVideoGenerationResponse — id, status, videos[].

Если Gemini фильтрует контент по safety, status = failed, content_filter описывает причину.

Статусы задачи: in_progress → completed / failed.

Retrieve / Download

Video Delete, List и Remix не поддерживаются.

Поддерживаемые типы контента

Meridian поддерживает следующие модальности контента через Gemini:

Нюансы