Руководство
Как использовать gpt-6-sol через HiAPI API: curl, Python и один рабочий запрос
На этой странице
Что нужно подготовить перед первым вызовом
Прежде чем писать любой код, подготовьте три вещи. Всё остальное в этом руководстве строится на них.
API-ключ HiAPI
Каждый запрос к HiAPI API требует аутентификации с помощью API-ключа. Создайте ключ в панели управления вашей учётной записи HiAPI и сохраните его в надёжном месте, лучше всего в переменной окружения, а не в файле исходного кода. Относитесь к нему как к паролю: при утечке немедленно выполните ротацию.
export HIAPI_API_KEY="your-api-key-here"
Базовый эндпоинт
Все вызовы в этом руководстве отправляются на базовый эндпоинт HiAPI API, и каждая модель доступна через одну и ту же форму пути запроса. Вам не нужно отдельное имя хоста или SDK для каждой модели — gpt-6-sol выбирается в теле запроса, а не путём изменения настроек клиента.
HTTP-клиент
Вам понадобится одно из следующего:
curl, доступный по умолчанию в большинстве систем Linux и macOS, а также в терминале Windows.- Python с установленной библиотекой
requests(pip install requests) или, если вы не хотите добавлять зависимость, стандартная библиотекаurllib.
Другие инструменты не нужны. Вам не нужен SDK конкретного поставщика и не нужно устанавливать что-либо, связанное с моделью. Достаточно уметь отправить HTTPS POST-запрос с JSON-телом и заголовками — и вы сможете вызывать gpt-6-sol.
Одна привычка, которую стоит завести сейчас: держите черновой файл с рабочим запросом, который вы используете, чтобы при сбое можно было сравнить неудачный вызов с последним известным рабочим вызовом.
Аутентификация с помощью bearer-ключа
Аутентификация — самое частое место ошибок при первом вызове, поэтому стоит отнестись к ней внимательно.
Заголовок Authorization
HiAPI API ожидает ваш ключ в стандартном bearer-заголовке:
Authorization: Bearer $HIAPI_API_KEY
Это буквальное слово Bearer, пробел, затем ключ. Частые ошибки: пропуск слова Bearer, лишний перевод строки при копировании значения или добавление кавычек вокруг ключа, когда клиент уже сам добавляет кавычки.
Тип содержимого должен быть JSON
Запрос несёт JSON-тело, поэтому заголовок типа содержимого должен соответствовать:
Content-Type: application/json
Без этого заголовка некоторые серверы всё равно разбирают тело, но полагаться на это не следует — задавайте его явно. Несовпадение типа содержимого — частая причина ошибок валидации запроса, которые выглядят как ошибки тела.
Минимальный набор заголовков
Вам нужны только два заголовка выше:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Держите набор заголовков как можно меньшим. Предположительные заголовки, позаимствованные из примеров других API, чаще вызывают путаницу, чем помогают. Как только вызов с этими двумя заголовками сработает, у вас будет чистая база для сравнения в будущем.
Избегайте вставки ключа напрямую в историю оболочки или в коммитимые файлы. Ссылка на переменную окружения, как выше, держит ключ вне вашего исходного кода и истории терминала.
Формирование тела запроса для gpt-6-sol
Тело запроса — это JSON, в центре которого находится список сообщений. Начните с минимальной конфигурации; добавляйте поля только после успешного вызова.
Минимальная полезная нагрузка запроса
Минимальное полезное тело запроса требует указания модели и одного сообщения:
{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "Объясни в одном предложении, что такое bearer-токен API." }
]
}
Здесь задействованы два поля:
modelвыбираетgpt-6-sol, так что тот же эндпоинт позже сможет обслуживать и другие модели.messages— упорядоченный список реплик диалога. Каждый элемент имеетrole(system,userилиassistant) и строкуcontent.
Безопасные значения по умолчанию и необязательные дополнения
Считайте model и messages обязательными. Всё остальное необязательно и должно добавляться осознанно:
- Сообщение
systemв началеmessagesзадаёт поведение или тон диалога. Это обычное сообщение, а не отдельное поле верхнего уровня. - При необходимости управление длиной вывода задаётся параметрами в теле запроса. Добавляйте их, только если вывод по умолчанию слишком короткий или слишком длинный для вашего случая.
- Параметры сэмплирования меняют форму вывода, а не его валидность. Не меняйте их при отладке неудачного вызова, поскольку они не исправят ошибки аутентификации или структуры тела.
Одно практическое правило
При сбое полезная нагрузка запроса должна быть как можно ближе к минимальному примеру. Удаляйте необязательные поля по одному, пока вызов не сработает, затем добавляйте их обратно. Это быстро изолирует проблему: один плохой параметр найти легче, чем плохой параметр, скрытый среди пяти хороших.
Отправка одного рабочего запроса с помощью curl
Ниже — полная команда, которую можно запустить сразу, если ваш ключ экспортирован. Она использует заполнитель пути эндпоинта, соответствующий описанным выше соглашениям HiAPI API.
curl -sS -X POST "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "Объясни в одном предложении, что такое bearer-токен API." }
]
}'
Задайте HIAPI_BASE_URL равным базовому эндпоинту из вашей панели HiAPI. Флаги важны:
-X POSTзадаёт метод; эти вызовы всегда POST.-Hдобавляет каждый заголовок, по одному на строку.-dпередаёт JSON-тело. Одинарные кавычки защищают его от подстановки оболочкой.-sSсохраняет тихий вывод, но всё равно показывает ошибки, что и нужно при скриптовании.
Чтение ответа
Успешный ответ — это JSON. Обычно вы увидите объект верхнего уровня с именем модели и списком choices, каждый choice содержит сообщение, чей content хранит сгенерированный текст. Сначала читайте структуру, затем тело: убедитесь, что объект разбирается, затем найдите поле content.
Для удобства чтения можно передать в форматировщик JSON:
... | python -m json.tool
Если вместо этого ваш терминал напечатал объект ошибки, вызов не удался — перейдите к разделу об ошибках, а не настраивайте промпт. Когда запрос вообще не дошёл до модели, проблема не в промпте.
Отправка того же запроса на Python
Полезную нагрузку, которую вы только что проверили в curl, можно перенести напрямую. Держите тело запроса точно таким же, чтобы исправления, проверенные в терминале, применялись и в коде.
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-6-sol",
"messages": [
{"role": "user", "content": "Объясни в одном предложении, что такое bearer-токен API."}
],
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
response = requests.post(
f"{base_url}/chat/completions",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
for choice in data.get("choices", []):
message = choice.get("message", {})
print(message.get("content", ""))
Почему эта версия безопаснее в коде приложения
- Тело запроса — это словарь. Когда вы передаёте
json=payload,requestsсериализует его и задаёт тип содержимого за вас, но явные заголовки предотвращают сюрпризы при смене клиента. - Ключ берётся из переменной окружения. Ни один секрет не захардкожен, поэтому этот файл можно коммитить.
raise_for_status()выполняется первым. Ответы не из диапазона 2xx сразу вызывают исключение — до того, как вы попытаетесь прочитать отсутствующее поле в теле ответа с ошибкой.- Установлен таймаут. Без таймаута зависшее соединение может бесконечно подвесить рабочий процесс.
Цикл по choices также защищает от отсутствия ключа, что делает пример устойчивым к ответам с малым объёмом вывода или без него. Стройте свою производственную обёртку вокруг этого скелета: проверка, отправка, проверка статуса, затем разбор.
Потоковое получение ответа вместо ожидания
По умолчанию API возвращает полный ответ в одном JSON-ответе. Для длинного вывода или интерактивных интерфейсов можно вместо этого запросить постепенную доставку ответа по мере генерации.
Переключатель потоковой передачи
Потоковая передача включается флагом в теле запроса, а не отдельным эндпоинтом:
{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "Напиши короткий текст о HTTP-кодах состояния." }
],
"stream": true
}
Добавьте этот флаг последним, после того как непоточный вызов уже работает. Он меняет способ организации ответа, а не то, валиден ли запрос.
Потребление инкрементального вывода
При включённой потоковой передаче ответ — это уже не единый JSON-документ. Он приходит в виде серии событий, обычно разделённых строками, каждое из которых несёт небольшой фрагмент вывода. Ваш клиент должен читать их по мере поступления, а не вызывать .json() для всего тела ответа.
with requests.post(
f"{base_url}/chat/completions",
headers=headers,
json=payload,
stream=True,
timeout=60,
) as response:
response.raise_for_status()
for line in response.iter_lines():
if line:
print(line.decode("utf-8"))
В терминале тот же флаг ведёт себя иначе, чем непоточный вызов: вывод появляется постепенно, поэтому прерванный пайплайн может выглядеть как неудачный запрос, тогда как на самом деле поток был просто прерван.
Что выбрать
Используйте непоточный режим для пакетных задач, тестирования и любого случая, когда нужен полный объект сразу. Используйте потоковый режим, когда кто-то ждёт текст или вывод настолько длинный, что задержка заметна. Держите в кодовой базе оба пути, поскольку непоточный путь проще отлаживать.
Чтение и исправление распространённых кодов ошибок
Сначала диагностируйте по коду состояния, затем по телу ответа. Не меняйте модель и не переписывайте промпт, пока не определите, какой уровень отказал.
401 Unauthorized
Причина: ключ отсутствует, имеет неверный формат или отозван. Исправление: убедитесь, что заголовок точно имеет вид Authorization: Bearer <key>, проверьте наличие скрытых пробельных символов или устаревших переменных окружения и подтвердите, что ключ всё ещё действителен в вашей панели. Печатайте длину переменной, а не значение, чтобы отловить ошибку пустой переменной.
400 Bad Request
Причина: тело запроса не разбирается или в нём отсутствуют обязательные поля. Исправление: отправьте снова минимальную полезную нагрузку, содержащую только model и messages. Проверьте JSON с помощью python -m json.tool перед отправкой; висячие запятые или опечатки в model — частые причины. Убедитесь, что Content-Type равен application/json.
403 Forbidden
Причина: ключ действителен, но нет доступа к запрашиваемому ресурсу. Исправление: проверьте, имеет ли ваша учётная запись доступ к gpt-6-sol, и соответствует ли имя модели в теле запроса тому, что настроено для вашей учётной записи.
404 Not Found
Причина: неверный путь URL, обычно опечатка в эндпоинте или отсутствующий либо дублирующийся базовый путь. Исправление: сравните полный URL посимвольно с рабочим вызовом curl.
429 Too Many Requests
Причина: вы отправляете запросы быстрее, чем позволяет ваша учётная запись. Исправление: отступите и повторите с увеличивающейся задержкой. Соблюдайте любые рекомендации по повторным попыткам из заголовков ответа и никогда не повторяйте в тесном цикле — это усугубит проблему. Отличайте это от 5xx, которые означают проблему на стороне сервиса, а не вашу скорость запросов.
5xx Ошибки сервера
Причина: сервис не может обработать в остальном валидный запрос. Исправление: повторите с отступлением; если проблема сохраняется, зафиксируйте тело ответа и ID запроса и избегайте изменения полезной нагрузки, поскольку она уже работает.
Повторяемый порядок отладки
- Код состояния — это проблема аутентификации, пути или тела?
- Тело ответа — указывает ли оно на проблемное поле?
- Структура полезной нагрузки запроса — вернитесь к минимальному примеру.
- Только в конце рассматривайте промпт или параметры.
Этот порядок последовательно сокращает время от сбоя до исправления. Как только ваши вызовы стабилизируются, держите рабочие версии curl и Python рядом, чтобы каждое будущее тестирование начиналось с известного рабочего состояния.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий