Как вызывать gpt-5.6-terra@azure через HiAPI API: руководство по curl и Python

Что означает gpt-5.6-terra@azure в запросе к HiAPI

В запросе к HiAPI gpt-5.6-terra@azure — это идентификатор модели: его нужно поместить в поле model тела запроса чата. Это всё, что требуется от вас. Вам не нужно конструировать URL, специфичный для провайдера, менять SDK или изменять структуру тела запроса.

Суффикс @azure — это метаданные маршрутизации: он сообщает HiAPI, какой бэкенд должен обрабатывать запросы для этого варианта модели. Всё остальное в теле запроса — messages, temperature, max_tokens, stream, tools — сохраняет знакомую вам стандартную структуру chat-completions. На практике это важно: если у вас уже есть работающий запрос к другой модели в HiAPI, переход на gpt-5.6-terra@azure обычно требует изменения одной строки.

{
  "model": "gpt-5.6-terra@azure",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

Две привычки сводят ошибки, связанные с идентификатором модели, почти к нулю:

• Относитесь к ID как к непрозрачной строке. Копируйте его как есть, включая @ и суффикс в нижнем регистре. Без пробелов, без изменения регистра.
• Храните его в конфигурации, а не разбрасывайте по коду. Использование константы или переменной окружения превращает A/B-тестирование разных ID моделей в правку конфигурации, а не в рефакторинг.

Поскольку суффикс отвечает за маршрутизацию, вам не следует делать выводы о нижележащем стеке услуг только по ID. Задержка, ограничения и поддерживаемые параметры — это свойства, которыми обладает модель в том виде, в каком её предоставляет HiAPI, поэтому сначала проверьте поведение небольшим запросом, а уже потом закладывайте предположения в приложение.

Предварительные требования и подготовка ключа

Перед первым вызовом убедитесь в трёх вещах:

1. Аккаунт HiAPI. Вам нужно войти, чтобы создать учётные данные и посмотреть актуальную информацию о моделях и ценах в консоли.
2. API-ключ. Сгенерируйте его в консоли и храните в надёжном месте — обращайтесь с ним как с паролем. Это руководство не предполагает конкретного формата ключа; любая строка, которую выдаёт консоль, — это значение для заголовка Authorization.
3. HTTP-клиент. Используйте curl для быстрой проверки, а Python 3 с requests или SDK, совместимым с OpenAI, — для написания кода приложения.

Держите ключ подальше от исходных файлов

Используйте переменные окружения. Этот шаблон одинаков на всех платформах:

export HIAPI_API_KEY="your-key-here"

Затем ссылайтесь на неё во время выполнения. В shell: "$HIAPI_API_KEY". В Python: os.environ["HIAPI_API_KEY"]. В CI используйте хранилище секретов, предоставляемое вашим провайдером, а не коммитьте файл .env.

Если вы вставили ключ в терминал для отладки, помните, что он может остаться в истории shell — если это реальные учётные данные, впоследствии их нужно сменить. Для локальной разработки одноразовый ключ только для тестов проще контролировать, чем повторное использование производственных учётных данных.

Убедитесь в правильности Base URL и эндпоинта

HiAPI предоставляет эндпоинт chat completions, совместимый с OpenAI. Возьмите base URL и путь из документации вашей консоли и используйте их согласованно в curl и Python — большинство сообщений «curl работает, а Python нет» сводится к завершающему слэшу или отсутствующему сегменту пути.

Рабочий запрос curl

Ниже приведён минимальный корректный вызов. Замените base URL на тот, что указан в вашей консоли, и убедитесь, что HIAPI_API_KEY экспортирована.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra@azure",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API gateway does in two sentences."}
    ],
    "max_tokens": 200
  }'

Разбор по полям:

• -sS скрывает индикатор прогресса, но по-прежнему показывает ошибки. Если вы хотите видеть заголовки ответа вместе с телом, добавьте -i.
• Authorization: Bearer $HIAPI_API_KEY аутентифицирует запрос. Префикс Bearer и пробел после него обязательны.
• Content-Type: application/json — если его опустить, многие серверы отклонят запрос ещё до разбора тела.
• model — точный ID gpt-5.6-terra@azure.
• messages — упорядоченный массив. system задаёт поведение; user содержит подсказку. В многоходовом диалоге по порядку добавляются ходы assistant и user.
• max_tokens — верхний предел длины ответа. Для быстрой проверки держите его небольшим, чтобы сбой обходился дёшево и быстро.

Успешный ответ — это JSON с массивом choices; нужный вам текст находится в choices[0].message.content. В первые разы прогоняйте вывод через инструмент форматирования JSON, чтобы видеть структуру, а не разбираться в одной длинной строке.

Как только этот запрос заработает, сохраните его как shell-скрипт, читающий ключ из переменной окружения. Так у вас появится воспроизводимая проверка работоспособности, которую можно запускать при каждом изменении ID модели или параметров.

Эквивалентный запрос на Python

Тело запроса точно такое же — меняется только способ передачи. Используя requests:

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API gateway does in two sentences."},
    ],
    "max_tokens": 200,
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

Три детали, которые стоит сохранить: используйте json=payload, а не ручную сериализацию (это установит заголовки и кодировку за вас), всегда задавайте timeout и вызывайте raise_for_status(), чтобы коды 4xx или 5xx проявлялись как исключения, а не приводили к IndexError при попытке индексировать тело ответа с ошибкой.

Стиль SDK провайдера

Поскольку эндпоинт совместим с OpenAI, SDK с настроенным кастомным base URL сформирует тот же запрос:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)

completion = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Say hello in one word."}],
    max_tokens=50,
)
print(completion.choices[0].message.content)

Смысл демонстрации обоих способов в том, что ID модели — единственная переменная, определяющая, какая модель вас обслуживает. Всё остальное — обычный конвейер chat-completions, поэтому вы можете переключаться между сырым HTTP и SDK, не переписывая логику.

Добавление потоковой передачи и вызова инструментов

Обе возможности добавляются инкрементально. Вы не переписываете базовый запрос — вы добавляете поля и меняете способ потребления ответа.

Потоковая передача

Установите "stream": true в теле запроса:

stream = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Count from 1 to 10."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Ответ превращается в последовательность событий, отправляемых сервером, вместо одного JSON-объекта. Каждый блок несёт delta с фрагментом содержимого; в первом и последнем блоках delta.content может быть None, поэтому перед конкатенацией проверяйте значение. С сырым HTTP всё аналогично — читайте тело построчно, отбрасывайте префикс data: , пропускайте [DONE] и разбирайте каждую строку JSON.

Вызов инструментов

Опишите инструменты в запросе, чтобы модель решала, когда их вызывать:

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [{"role": "user", "content": "What's the weather in Berlin?"}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
    "tool_choice": "auto",
}

Когда модель хочет вызвать инструмент, choices[0].message будет содержать массив tool_calls, а не простой текст. Каждый элемент имеет id и function, где function содержит name и arguments (строку JSON, которую вам нужно разобрать). Выполните свою функцию, затем отправьте результат обратно как сообщение с role: "tool", указав соответствующий tool_call_id и сериализованный вывод — и снова сделайте запрос, чтобы получить финальный ответ.

tool_choice принимает "auto" (решает модель), "none" (только текст) или конкретную функцию. Потоковую передачу и инструменты можно комбинировать, но аргументы вызова инструмента приходят фрагментами по разным блокам, и их нужно сначала накопить, а потом разбирать — поэтому сначала добейтесь работы непоточного вызова инструментов.

Диагностика типичных ошибок запросов

Отлаживайте в таком порядке; каждый шаг изолирует один слой, чтобы вы не гнались за двумя проблемами одновременно.

1. Аутентификация (401 / 403)

Наиболее вероятные причины: отсутствующий ключ, потерянный префикс Bearer или переменная окружения, разворачивающаяся в пустую строку. Выведите способ формирования заголовка, не показывая полный ключ, и убедитесь, что переменная задана в том же shell или процессе, где выполняется запрос.

2. Эндпоинт и путь (404)

404 обычно означает неверный путь — опечатку, отсутствующий /v1 или лишний завершающий слэш там, где его быть не должно. Скопируйте точный URL из консоли, а не вводите его заново.

3. ID модели (400 с сообщением о модели)

ID должен совпадать точно: gpt-5.6-terra@azure. Типичные ошибки — изменение регистра, отсутствие @azure или лишние пробелы из-за копирования и вставки. Если сообщение говорит, что модель неизвестна, сначала сравните настроенную строку со списком в консоли посимвольно, и только потом подозревайте сбой сервиса.

4. Некорректный формат тела запроса (400 / 422)

Если ошибка упоминает тело запроса, сначала проверьте валидность JSON — частые виновники — завершающие запятые или неэкранированные кавычки. Затем проверьте имена полей (messages, а не message) и роли (system, user, assistant, tool). max_tokens должен быть числом, tools — массивом корректно структурированных объектов.

5. Обработка потокового ответа как обычного JSON

Если вывод пуст, искажён или вызывает ошибку разбора, скорее всего, вы запросили stream: true, но разбираете ответ как единый JSON-документ. Читайте его как поток событий, пропускайте [DONE] и защищайтесь от None-дельт.

6. Таймаут клиента

Длительная генерация может превысить таймаут HTTP по умолчанию. Увеличьте его явно на стороне клиента или переключитесь на потоковую передачу, чтобы байты начали поступать немедленно.

Краткий чек-лист для быстрого воспроизведения

• Выполните минималистичный вызов curl. Если он успешен, проблема в вашем коде.
• Если он не удался, повторите попытку в новом shell с вашим ключом и ID модели.
• Записывайте одновременно HTTP-статус и тело ответа — тело ответа с ошибкой содержит диагностические подробности.
• Только после того, как все эти проверки пройдены, стоит подозревать проблему на стороне сервера, достойную эскалации.

Имея работающий запрос, цикл потоковой передачи и этот чек-лист, gpt-5.6-terra@azure будет вести себя в вашем стеке так же, как и другие чат-модели, — а смена модели превратится в одну строку изменения в конфигурации.