Как подключить Gemini 4 Neon API? Первый запрос через нативный и OpenAI-совместимый интерфейс APIYI

Как подключить Gemini 4 Neon API? Первый запрос через нативный и OpenAI-совместимый интерфейс APIYI

Примечание автора: в этой статье рассказывается, как через APIYI с помощью двух протоколов отправить первый запрос к Gemini 4 Neon, а также какие поля и логи нужно проверить после успешного ответа.

Сразу к делу: если в проекте уже есть клиент OpenAI Chat, идите через совместимую с OpenAI точку входа Chat Completions — достаточно заменить base_url и имя модели. Если нужно явно задать уровень размышлений Gemini, идите через нативную точку входа generateContent и указывайте его в generationConfig.thinkingConfig.thinkingLevel. Какой бы путь вы ни выбрали, сначала прогоните один и тот же короткий промпт на чистом тексте, а потом устраивайте приёмку по HTTP-статусу, телу ответа, причине остановки, расходу токенов и логам платформы. Когда приёмка пройдена, можно тестировать потоковый вывод, вызов инструментов и прочие возможности.

Предыстория такая. Google в обновлении AI Studio от 18 ноября 2026 года выпустил Gemini 4 Neon и объявил GA. APIYI подтвердил появление модели в каталоге по пекинскому времени 2026-11-20 11:45, в публичном прайс-листе видно gemini-4-neon, доступные группы — default и svip. Примеры в этой статье написаны по документации APIYI и документации SDK, платные интерфейсы не вызывались, никаких статистических данных реальных замеров в тексте нет.

gemini-4-neon-api-first-request-native-openai-compatible-ru-image-0


Карта знаний и указатель по подключению к API Gemini 4 Neon

Весь процесс подключения состоит из трёх шагов: выбрать интерфейс, отправить запрос, проверить вывод и журналы. Результат каждого шага становится входными данными для следующего. Таблицу ниже можно использовать и как карту знаний, и как указатель для чтения: в ней собраны порядок этих трёх шагов, логика их расположения и цель каждого этапа.

№ Шаг Что даёт предыдущий шаг Почему шаги идут именно так Цель шага
1 Выбор входа (1.1 Chat-совместимый / 1.2 нативный режим и уровень мышления) Ваш текущий стек кода и требования к уровню мышления Вход определяет URL, способ аутентификации и структуру полей; от него зависят все последующие шаги Выбрать один протокол и не отлаживать два пути одновременно
2 Отправка одного и того же короткого запроса (2.1 нативный cURL / 2.2 Python SDK) Уже выбранный вход и формат запроса Фиксированный короткий промпт позволяет исключить различия в возможностях моделей и проверить только работоспособность цепочки Получить полный код состояния, заголовки ответа и тело ответа
3 Проверка (3.1 поля / 3.2 идентификация и журналы / 3.3 фиксация доказательств при сбое) Исходный ответ, сохранённый на шаге 2 Сначала смотрим на сам ответ, затем сверяем его с журналами платформы; доказательства собираем от ближних к дальним Определить, действительно ли «текстовый ответ успешен»; если нет — оставить проверяемые доказательства

Совет по чтению: если вы используете только один протокол, после чтения соответствующего подраздела раздела 1 сразу переходите к 2.1 или 2.2; раздел 3 нужно читать полностью.

gemini-4-neon-api-first-request-native-openai-compatible-ru-image-1

Что нужно знать: необходимые термины API Gemini 4 Neon

Термин Краткое объяснение
generateContent Нативный нестриминговый интерфейс генерации Gemini; в теле запроса содержимое организуется через contents и parts
thinkingLevel Поле уровня мышления в generationConfig.thinkingConfig нативного интерфейса; в примерах этой статьи используется high
thought part Part в нативном ответе, помеченный как содержимое мышления; при сборке основного текста его нужно исключить
finishReason / finish_reason Поля причины остановки в нативном и совместимом интерфейсах соответственно
X-Shellapi-Request-Id Идентификатор запроса, который APIYI возвращает в исходных заголовках ответа или в сообщении об ошибке; используется для диагностики

1 Выбор точки подключения API Gemini 4 Neon

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

Параметр сравнения OpenAI-совместимый Chat Нативный Gemini
Адрес https://api.apiyi.com/v1 + Chat Completions https://api.apiyi.com/v1beta/models/gemini-4-neon:generateContent
Для кого Проекты, где уже есть OpenAI SDK или Chat-клиент Проекты, где нужен явный контроль параметров Gemini
Уровень рассуждений В этой статье соответствующие параметры не передаются thinkingConfig.thinkingLevel
Где находится основной текст choices[0].message.content text (не thought) в candidates[0].content.parts
Идентификатор модели model в ответе modelVersion в ответе (если возвращается)

1.1 Совместимый вход Gemini 4 Neon: используем существующий Chat-клиент

Если код уже построен на OpenAI Python SDK или другом клиенте Chat Completions, минимальное изменение — заменить base_url на https://api.apiyi.com/v1 и указать имя модели gemini-4-neon, структуру сообщений при этом менять не нужно. Плюс в том, что код бизнес-логики почти не правится, а при возникновении проблем проще понять, дело в сети, аутентификации или самой модели.

У этого пути есть несколько границ, которые стоит обозначить. Во-первых, не передавайте reasoning_effort. Собственный слой совместимости Google его маппит, но это не значит, что совместимый вход APIYI берёт на себя те же обязательства. Во-вторых, в этой статье не используется эндпоинт /v1/responses. В-третьих, старый способ записи thinkingBudget и уровень minimal тоже вне рамок статьи. Если вам действительно нужно управлять уровнем рассуждений, переходите к нативному входу из 1.2.

1.2 Нативный вход Gemini 4 Neon: явно задаём уровень рассуждений

Нативный вход использует собственную структуру запроса Gemini. Уровень рассуждений передаётся явно через generationConfig.thinkingConfig.thinkingLevel, в специализированном примере APIYI используется значение "high". Нативный ответ также разделяет содержание рассуждений и основной текст на разные part, поэтому при чтении основного текста нужно активно фильтровать — конкретный код приведён в разделе 2.1.

Что касается аутентификации, в этом нативном примере используется заголовок Authorization: Bearer, а не распространённая у официального Gemini запись с параметром key. При миграции существующего нативного кода сначала проверьте этот момент.


2 Отправка одного и того же короткого запроса в Gemini 4 Neon API

Оба протокола используют один и тот же промпт: Reply with exactly NEON_OK and nothing else. Ожидаемый вывод по этому промпту очень короткий, и результат легко проверить. Если вернулось что-то кроме NEON_OK, значит проблема в цепочке или в разборе ответа — так можно отбросить помехи вроде «модель просто отвечает в другом стиле». API-ключ всегда читается из переменной окружения APIYI_API_KEY, не записывайте его в код или в историю команд.

2.1 Нативный cURL для Gemini 4 Neon и извлечение значений из JSON

Приведённая ниже команда сохраняет HTTP-код статуса, заголовки ответа и тело JSON-ответа по отдельности — все три понадобятся при приёмке в разделе 3.

curl -sS -X POST "https://api.apiyi.com/v1beta/models/gemini-4-neon:generateContent" \
  -H "Authorization: Bearer ${APIYI_API_KEY}" \
  -H "Content-Type: application/json" \
  -D neon_native_headers.txt \
  -o neon_native_body.json \
  -w "%{http_code}\n" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Reply with exactly NEON_OK and nothing else."}]}
    ],
    "generationConfig": {
      "thinkingConfig": {"thinkingLevel": "high"}
    }
  }' > neon_native_status.txt

При чтении основного текста нужно склеить все text из candidates[0].content.parts, которые не являются thought, а не брать только первую part. В примере ниже используется jq; если jq не установлен, можно взять любой другой инструмент разбора JSON:

# Основной текст: склеиваем text, не являющиеся thought
jq -r '[.candidates[0].content.parts[]? | select(.thought != true) | .text // empty] | join("")' neon_native_body.json

# Причина остановки, расход, версия модели (если поля нет — выводится null, не подставляйте значение сами)
jq '{finishReason: .candidates[0].finishReason, usageMetadata, modelVersion}' neon_native_body.json

# Идентификатор запроса платформы
grep -i "x-shellapi-request-id" neon_native_headers.txt

2.2 Вызов Gemini 4 Neon через Python OpenAI SDK и чтение ответа

Совместимый эндпоинт использует with_raw_response — так можно получить и разобранный объект, и исходные заголовки ответа. max_retries=0 отключает автоматические повторы SDK, чтобы одна неудача не маскировалась ретраями, а на платформе не появлялось несколько логов, по которым непонятно, к какому именно запросу они относятся.

import os
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1",  # OpenAI-совместимый эндпоинт APIYI
    max_retries=0,
    timeout=120.0,
)

try:
    raw = client.chat.completions.with_raw_response.create(
        model="gemini-4-neon",
        messages=[{"role": "user", "content": "Reply with exactly NEON_OK and nothing else."}],
        max_tokens=4096,
    )
    print("HTTP:", raw.status_code)
    print("X-Shellapi-Request-Id:", raw.headers.get("x-shellapi-request-id"))

    completion = raw.parse()
    if not completion.choices:
        print("choices 为空,不读取正文")
    else:
        choice = completion.choices[0]
        print("content:", choice.message.content)
        print("finish_reason:", choice.finish_reason)
    print("usage:", completion.usage)
    print("model:", completion.model)

except APIStatusError as e:
    print("HTTP:", e.status_code)
    print("X-Shellapi-Request-Id:", e.response.headers.get("x-shellapi-request-id"))
    print("error:", e.message)  # перед записью убедитесь, что нет ключей и других чувствительных данных
except APIConnectionError as e:
    print("未拿到 HTTP 响应:", type(e).__name__)

В этом коде есть один момент, на который стоит обратить особое внимание: когда choices пуст, нельзя сразу обращаться к choices[0], иначе возникнет ошибка индексации и скроет настоящую проблему. У ошибки соединения нет HTTP-статуса и заголовков ответа, поэтому её нужно обрабатывать отдельно от APIStatusError.


3 Приёмка первого запроса к Gemini 4 Neon API

Цель приёмки — понять, выполняется ли условие «текстовый запрос прошёл успешно». Код HTTP 2xx и ожидаемое NEON_OK в теле ответа говорят лишь о том, что этот конкретный текстовый запрос удался. Это не подтверждает идентичность модели и не может считаться результатом теста производительности.

3.1 HTTP-статус, тело ответа, причина остановки и расход

Проверка Нативное поле Совместимое поле Условие прохождения
HTTP-статус сохранённый status raw.status_code 2xx
Тело ответа склейка text без thought-частей choices[0].message.content равно NEON_OK
Причина остановки candidates[0].finishReason choices[0].finish_reason записана и согласуется с телом ответа
Расход usageMetadata usage записан для сверки с логами

Если какого-то поля в ответе нет, помечайте его как «не возвращено» и не пытайтесь угадать значение по опыту. Причину остановки нужно смотреть вместе с телом ответа. Если тело пустое, а причина остановки не означает нормальное завершение, проблема обычно кроется в процессе генерации, а не в коде парсинга.

3.2 Нативный modelVersion, совместимый model и журналы: что каждый из них может прояснить

Эти элементы подтверждают разные вещи, и при фиксации результатов не стоит подменять один другим:

Информация Источник Что подтверждает Что не подтверждает
modelVersion Нативное тело ответа (если возвращается) Версия модели, которую ответ указывает сам Не может само по себе служить доказательством идентичности
model Тело совместимого ответа Имя модели, которое ответ указывает сам То же самое
Журнал платформы api.apiyi.com/log Позволяет свернуть этот вызов по времени, токену, модели и расходу В консоли не отображается ID запроса
X-Shellapi-Request-Id Заголовок исходного ответа или текст ошибки Идентификатор запроса, который платформа использует для диагностики Это не responseId, не Chat id и не _request_id из SDK

При сверке с журналами сопоставляйте время отправки запроса, использованный токен, имя модели gemini-4-neon и цифры расхода. Поскольку консоль не отображает ID запроса, X-Shellapi-Request-Id нужно самостоятельно сохранить из заголовков ответа — потом в консоли его не найти.

gemini-4-neon-api-first-request-native-openai-compatible-ru-image-2

3.3 Gemini 4 Neon: как фиксировать доказательства, если тело ответа отсутствует или запрос завершился ошибкой

Когда запрос падает или тело ответа пустое, не спешите с повтором — сначала сохраните доказательства в таком порядке:

  1. Сохраните код состояния HTTP. Если это ошибка соединения — запишите тип исключения.
  2. Сохраните исходные заголовки ответа и вытащите из них X-Shellapi-Request-Id.
  3. Сохраните сырое тело ответа или сообщение об ошибке, предварительно удалив чувствительные данные вроде API-ключа.
  4. Зафиксируйте причину остановки и расход (если он есть), а также время отправки запроса, имя использованного токена и название модели.
  5. Зайдите на api.apiyi.com/log, найдите нужную запись по времени и токену и с этими материалами сверьтесь с документацией платформы по траблшутингу через request ID.

Есть ещё один нюанс про нативный ответ. Если в parts лежит только thought-контент, после фильтрации тело окажется пустым. В этом случае так и пишите: «после фильтрации тело пустое» — не выдавайте thought-контент за тело только ради того, чтобы получить хоть какой-то вывод.


Когда одиночный текстовый запрос прошёл приёмку по описанной схеме, можно проверять потоковый вывод, вызов инструментов и другие возможности — смотря что нужно проекту. Каждую новую возможность принимайте отдельно по одному и тому же принципу: «тот же запрос, сохранить исходный ответ, свер-ить с логами». Бенчмарки и цены в этой статье не разбираются — актуальное смотрите в официальных анонсах и публичном каталоге APIYI.

Ссылки

  1. Журнал обновлений Google AI Studio (2026-11-18): aistudio.google.com/docs/changelog
  2. Структура Gemini GenerateContentResponse: aistudio.google.com/api-reference/generate-content
  3. Анонс выхода Gemini 4 Neon от APIYI и примеры для двух протоколов: docs.apiyi.com/news/gemini-4-neon-launch.md
  4. Обработка ответов Gemini в APIYI: docs.apiyi.com/api-capabilities/gemini/response-handling
  5. Обработка ответов, совместимых с OpenAI, в APIYI: docs.apiyi.com/api-capabilities/openai/response-handling
  6. Траблшутинг по request ID в APIYI: docs.apiyi.com/faq/request-id-troubleshooting
  7. Доступ к сырому ответу в openai-python: github.com/openai/openai-python

Путь в тысячу ли начинается с первого шага. — «Дао дэ цзин»

Похожие записи