формат google gemini

формат google gemini устроен иначе, чем формат openai: имя модели передаётся в адресе, а не в теле запроса. поэтому для него выделен отдельный базовый путь — /v1beta.

запрос

адрес собирается из имени модели и метода: POST /v1beta/models/gemini-3.5-flash:generateContent. текст запроса передаётся в поле contents.

официальные библиотеки google дописывают путь /v1beta/models/… сами, поэтому в качестве базового адреса им указывается https://api.airakurs.ru.

curl "https://api.airakurs.ru/v1beta/models/gemini-3.5-flash:generateContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: <КЛЮЧ>" \
    -d '{
        "contents": [
            {"parts": [{"text": "Назови столицу Австралии."}]}
        ]
    }'

ключ передаётся заголовком x-goog-api-key или параметром ?key= — так его отправляют официальные библиотеки google. заголовок Authorization тоже работает.

имя модели в адресе указывается коротким, без вендора. на этом пути доступны модели google; для моделей остальных вендоров нужен /v1.

потоковый вариант того же метода — :streamGenerateContent с параметром alt=sse в строке запроса.

ответ

текст лежит в первом элементе массива candidates, внутри content.parts:

{
    "candidates": [
        {
            "content": {
                "role": "model",
                "parts": [
                    {"text": "Канберра."}
                ]
            },
            "finishReason": "STOP"
        }
    ],
    "usageMetadata": {
        "promptTokenCount": 8,
        "candidatesTokenCount": 4,
        "totalTokenCount": 12
    }
}

в официальных библиотеках разбирать массив вручную не нужно — готовый текст лежит в поле text.

подсчёт токенов

метод :countTokens считает, сколько токенов займёт запрос, не выполняя его: POST /v1beta/models/gemini-3.5-flash:countTokens.

список моделей

GET /v1beta/models возвращает список в формате google. в нём только модели google — полный каталог отдаёт /v1/models.

что дальше

• единый api — базовый формат запроса и ответа.
• модели — как устроены идентификаторы.

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