Руководство
Gemini-4 Argon и Carbon на HiAPI: curl, Python и рабочие запросы
Практическое руководство по интеграции для разработчиков, выбирающих между gemini-4-argon, gemini-4-carbon и gemini-4-carbon@vertex
На этой странице
Выберите вариант Gemini-4 до того, как писать код
Первое решение при любой интеграции Gemini-4 — не curl или Python, а то, какой идентификатор модели вы отправляете. В HiAPI gemini-4-argon, gemini-4-carbon и gemini-4-carbon@vertex — это три разные маршрутизируемые цели, и строка, которую вы передаёте в поле model, определяет, какой бэкенд обслужит ваш запрос. Выбрав её заранее, вы избавите себя от отладки тела запроса, которое изначально не может работать.
Три цели на практике
gemini-4-argon— самостоятельный вариант Gemini-4 со своим идентификатором модели. Относитесь к нему как к отдельной модели, а не как к псевдониму: его поведение, характеристики задержки и особенности вывода могут отличаться от Carbon.gemini-4-carbon— цель Carbon по умолчанию при стандартной маршрутизации HiAPI.gemini-4-carbon@vertex— то же семейство Carbon, но обслуживаемое через маршрут на базе Vertex. Суффикс@vertexявляется частью самого идентификатора модели, а не отдельным параметром.
Как выбрать
Отталкивайтесь от рабочей нагрузки. Если вы широко оцениваете Gemini-4, прогоните один и тот же промпт через gemini-4-argon и gemini-4-carbon по отдельности и сравните выводы, прежде чем закреплять выбор. Если вам действительно нужна маршрутизация через Vertex — например, потому что она соответствует среде, которую ваша команда уже эксплуатирует, — сразу нацеливайтесь на gemini-4-carbon@vertex.
Практический момент: все три используют одну и ту же структуру запроса. Выбор варианта — это изменение одной строки, так что вы можете отложить окончательное решение до момента, когда у вас будет рабочий запрос. Если хотите сначала посмотреть карточки моделей, см. gemini-4-argon и gemini-4-carbon.
Примеры в этом руководстве на протяжении всего текста используют gemini-4-carbon; чтобы повторить действия с любым вариантом, просто замените этот ID.
Подготовьте учётные данные и базовый URL
Прежде чем любое тело запроса станет важным, нужно убедиться в правильности трёх вещей: базового URL, API-ключа и формата заголовка аутентификации. Большинство первых неудачных запросов связаны с одной из этих трёх вещей.
Что вам понадобится
- API-ключ из панели управления вашей учётной записи HiAPI. Относитесь к нему как к секрету — загружайте из переменной окружения, а не вставляйте в исходные файлы.
- Базовый URL HiAPI. Все вызовы моделей отправляются на один и тот же хост; вариант модели выбирается полем
model, а не путём. - Два заголовка в каждом запросе:
Authorization: Bearer $HIAPI_API_KEYContent-Type: application/json
Настройте окружение
export HIAPI_API_KEY="your-key-here"
Затем, прежде чем писать любой код, убедитесь, что ваша оболочка его видит:
echo "${HIAPI_API_KEY:0:4}..."
Если ничего не выводится, значит ваш ключ не экспортирован в текущей оболочке, и каждый запрос будет падать с ошибкой аутентификации. Исправьте это здесь, а не в своём клиенте.
Структура запроса, которую вы будете использовать постоянно
Каждый пример ниже отправляет JSON-тело, содержащее строку model и массив messages. Эта структура не меняется между curl и Python, между потоковым и непоточным режимами и между вариантами моделей. Держите её стабильной, и вы сможете переносить код, просто копируя тело запроса.
Рабочий запрос curl
Ниже — полный непоточный вызов, готовый к копированию. Запустите его до того, как добавлять что-либо ещё: если этот запрос проходит, значит ваш ключ, базовый URL и заголовки верны.
curl -sS "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an idempotency key is in two sentences."}
]
}'
Что делает каждое поле
model— селектор варианта. Замените его наgemini-4-argonилиgemini-4-carbon@vertex, и без каких-либо других изменений попадёте в другую цель.messages— упорядоченный массив. Роли:system,userиassistant. Если вы используете системное сообщение, поставьте его первым.content— текст сообщения. Для простых текстовых ходов это обычная строка.
Чтение тела ответа
Ответ — это JSON-объект, содержащий ответ модели и метаданные, такие как расход токенов. Поскольку это непоточный режим, всё тело приходит сразу, а curl завершается после вывода. Если вы получили разбираемый JSON-объект с ответом-сообщением, ваш запрос работает — всё последующее строится на этой базовой линии.
Быстрая проверка: пропустите вывод через форматтер JSON (| jq .), чтобы структура ответа читалась наглядно, а не сливалась в одну длинную строку.
Отправьте тот же запрос на Python
Версия на Python сохраняет тело запроса абсолютно идентичным — меняется только транспорт. Используйте requests:
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an idempotency key is in two sentences."},
],
}
response = requests.post(
f"{base_url}/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])
Почему это полностью соответствует вызову curl
Обратите внимание, что payload побайтово совпадает с JSON-телом из предыдущего раздела. Параметр json= сериализует его и сам устанавливает Content-Type; словарь заголовков обеспечивает аутентификацию. Модель, сообщения и роли не изменились.
Две привычки, которые стоит сохранить
- Задавайте таймаут. Без таймаута зависшее соединение подвесит ваш процесс на неопределённое время. Для непоточных вызовов
timeout=60— разумная отправная точка. - Вызывайте
raise_for_status()до чтения тела ответа. Неудачные запросы возвращают структурированный объект ошибки, а не завершение — проверкаjson()при 4xx введёт вас в заблуждение. Сначала дайте исключению всплыть, затем запишите текст ответа.
Вынесите тело запроса в функцию или небольшой объект конфигурации, чтобы разделы про стриминг и вызов инструментов могли его расширять, а не копировать.
Добавьте поддержку стриминга к вызову
Сначала добейтесь прохождения непоточного запроса. Затем включите стриминг — режимы отказа различаются, и накладывание двух изменений сразу делает ошибки неразличимыми.
Включение стриминга
Добавьте одно поле в существующее тело запроса:
{
"model": "gemini-4-carbon",
"stream": true,
"messages": [
{"role": "user", "content": "List three uses for a message queue."}
]
}
Это всё изменение протокола. Теперь сервер вернёт поток событий вместо одного JSON-документа.
Правильное потребление потока
Ключевое правило: не вызывайте .json() на потоковом ответе. Вы получите ошибку разбора, потому что тело ответа не является единым JSON-объектом. С requests итерируйте построчно и разбирайте каждый фрагмент отдельно:
import json, os, requests
response = requests.post(
f"{os.environ['HIAPI_BASE_URL']}/chat/completions",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "gemini-4-carbon",
"stream": True,
"messages": [{"role": "user", "content": "List three uses for a message queue."}],
},
stream=True,
timeout=60,
)
response.raise_for_status()
for line in response.iter_lines():
if not line:
continue
decoded = line.decode("utf-8")
if decoded.startswith("data: "):
decoded = decoded[len("data: "):]
if decoded.strip() == "[DONE]":
break
try:
chunk = json.loads(decoded)
except json.JSONDecodeError:
continue
print(chunk)
На что обратить внимание
- Передайте
stream=Trueвrequests. Иначе клиент сначала буферизует всё тело ответа, и вы увидите строку лишь после этого, что сводит весь смысл на нет. - Пропускайте пустые строки и не-JSON keep-alive сообщения. Приведённый выше
try/exceptсделан намеренно — поток может содержать строки, которые не разбираются как фрагмент. - Накапливайте текст между фрагментами. Каждый фрагмент несёт часть, а не полный ответ. Добавляйте текстовые дельты по мере их поступления.
Когда стриминг заработает, верните stream в false в ваших непоточных тестах, чтобы вызов инструментов оставался легко читаемым. Для обзора цели Carbon хорошей точкой отсчёта будет страница модели gemini-4-carbon.
Добавьте вызов инструментов в тело запроса
Вызов инструментов меняет запрос в двух местах: вы объявляете инструменты, и вам нужно обрабатывать ход ответа, который может содержать запрос на вызов инструмента вместо текста. Добавляйте эту возможность только после того, как непоточный текстовый вызов проходит.
Объявление инструментов
Добавьте массив tools рядом с model и messages. У каждого инструмента есть имя, описание и JSON Schema его параметров. Описание важно — именно по нему модель решает, вызывать ли этот инструмент.
{
"model": "gemini-4-carbon",
"messages": [
{"role": "user", "content": "What is the weather in Lisbon?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Return current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
}
]
}
Цикл вызова инструментов
Запрос с использованием инструментов — это диалог, а не однократный вызов:
- Отправьте сообщение пользователя вместе с объявлением инструментов.
- Проверьте ход ассистента. Если он содержит аргументы вызова инструмента, значит модель хочет, чтобы вы что-то выполнили.
- Выполните локальную функцию — HiAPI не запускает ваш код.
- Добавьте два сообщения: ход ассистента с вызовом инструмента и сообщение с ролью
toolс результатом функции, связанным с совпадающим ID вызова. - Отправьте повторно полную историю сообщений. Теперь модель выдаёт окончательный ответ.
Точки отказа, специфичные для инструментов
- Несоответствие схемы. Если ваша схема
parametersпомечает поле как обязательное, а в результате оно опущено, последующие ходы могут быть отклонены. Держите схему точной. - Потеря истории. Каждая повторная отправка должна включать исходное сообщение пользователя и ход с вызовом инструмента — а не только результат инструмента.
- Стриминг плюс инструменты. Аргументы вызова инструмента могут приходить, разбитыми на несколько фрагментов потока. Пока вы изучаете процесс, запускайте инструменты с
stream: false, чтобы каждый ход приходил одним читаемым объектом.
Переключение моделей и провайдеров без переписывания клиента
Поскольку вариант модели — это всего лишь строка в теле запроса, переключение цели является изменением конфигурации, а не рефакторингом. Проектируйте клиент так, чтобы он читал идентификатор модели из переменной — переменной окружения, файла конфигурации, флага CLI — и никогда не хардкодьте его в нескольких местах.
Само переключение
export HIAPI_MODEL="gemini-4-carbon" # default
export HIAPI_MODEL="gemini-4-argon" # different variant
export HIAPI_MODEL="gemini-4-carbon@vertex" # Vertex-backed Carbon
В коде ссылайтесь на эту переменную в теле запроса:
payload = {
"model": os.environ["HIAPI_MODEL"],
"messages": messages,
}
Суффикс @vertex передаётся вместе со строкой модели. Не выносите его в отдельное поле и не отбрасывайте — он является частью маршрутизируемого ID, и его удаление молча направит вас в цель, не использующую Vertex.
Что нужно перепроверить после переключения
- Чисто текстовые ходы — убедитесь, что ID распознаётся и аутентификация по-прежнему работает.
- Ваш самый длинный реальный промпт — разные варианты могут по-разному обрабатывать длинный или структурированный ввод; проверьте усечение и форматирование.
- Стриминг — повторно прогоните потоковый путь, поскольку ритм фрагментов и их границы могут различаться в зависимости от цели.
- Вызов инструментов — перепроверьте полный цикл вызова инструментов; формат аргументов — место, где различия вариантов проявляются чаще всего.
Держите небольшой скрипт дымового тестирования, который прогоняет эти четыре проверки для текущего значения HIAPI_MODEL. Тогда переключение провайдера станет изменением конфигурации и одной командой, а не сеансом отладки.
Устранение распространённых сбоев запросов
Почти каждый сбой интеграции сводится к нескольким категориям. Сопоставьте симптом, примените исправление и перед изменением чего-либо ещё повторно запустите непоточную базовую линию.
Аутентификация и маршрутизация
- 401 или 403. Ключ отсутствует, истёк или имеет неверный префикс. Проверьте, что заголовок в точности
Authorization: Bearer <key>с одним пробелом между частями, и убедитесь, что переменная действительно экспортирована в оболочке или процессе, запускающем код. Выведите первые несколько символов для подтверждения. - Эндпоинт возвращает 404. Ваш базовый URL неверен или сегмент пути дублируется. Модель указывается в теле запроса, а не в URL.
- Модель не найдена. Опечатка в идентификаторе модели. Сверьте посимвольно с
gemini-4-argon,gemini-4-carbonиgemini-4-carbon@vertex— суффикс@vertexчаще всего пропускают.
Проблемы с телом запроса
- 400 с сообщением о схеме. Обычно это неверный формат
messages: отсутствуетrole,contentдолжен быть строкой, но им не является, или массив пуст. Начните с минимального тела из двух строк в этом руководстве и добавляйте по одному полю за раз. - 400 после добавления инструментов. Ваша схема
parameters— недопустимая JSON Schema, или ход с результатом инструмента не соответствует ID вызова в сообщении ассистента. Запишите полное тело ответа — текст ошибки укажет проблемное поле.
Сбои стриминга
- Ошибка разбора JSON на ответе. Вы вызываете
.json()на потоке. Вместо этого итерируйте построчно, разбирайте каждый фрагмент и пропускайте пустые строки и маркер[DONE]. - Ответ приходит целиком сразу. Вы забыли установить
stream=Trueв вызове клиента, иrequestsбуферизовал всё тело ответа. - Вывод усечён. Ваш цикл прерывается слишком рано — обычно на пустой строке или keep-alive сообщении. Останавливайтесь только на явном маркере завершения потока.
Дисциплина отладки
Делите задачу пополам в том же порядке, в котором вы строили: аутентификация и заголовки, затем непоточный текст, затем стриминг, затем инструменты. У каждого слоя свои признаки отказа, поэтому почти всегда причина в том, что вы изменили последним. При каждом сбое записывайте HTTP-статус и полное тело ответа — сообщение обычно указывает конкретное поле.
Сначала добейтесь прохождения базовой линии на gemini-4-argon или gemini-4-carbon, затем расширяйте тело запроса. Если вы всё ещё решаете, какой вариант подходит для вашей нагрузки, страница модели gemini-4-argon — то, с чего стоит начать.
Похожие статьи
Все статьи →-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий
-
Руководство
Практические сценарии gemini-4-neon: 5 ценных способов применения и ключевые моменты интеграции
-
Руководство
Учебник по API seedance-2.5-flash для генерации видео из изображения: curl и Python Requests
Практическое руководство по интеграции для разработчиков: структура запроса, входные данные первого/последнего кадра, асинхронный опрос и устранение ошибок