Руководство
Как вызвать claude-opus-5-5@aws через HiAPI API: руководство по curl и Python
На этой странице
Как выглядит работа с claude-opus-5-5@aws через HiAPI
HiAPI предоставляет единый HTTP-интерфейс для множества моделей. Вам не нужно отдельно настраивать аккаунты, SDK и хранилища учётных данных для каждого провайдера — достаточно обращаться к HiAPI с одним и тем же форматом запроса и выбирать нужную модель через идентификатор модели. В этом руководстве такой идентификатор — claude-opus-5-5@aws; суффикс @aws является частью имени модели, а не отдельным полем, и должен передаваться как есть.
Жизненный цикл одного запроса выглядит так:
- Аутентификация — отправьте ваш API-ключ HiAPI в заголовке
Authorizationв виде bearer token. - Отправка чат-подобной полезной нагрузки — JSON-тело запроса с полем
modelи массивомmessages, где каждое сообщение содержитrole(system,userилиassistant) иcontent. - Получение JSON-ответа — ответ ассистента появляется в массиве
choicesответа вместе с метаданными об использовании. - Продолжение диалога — добавьте сообщение ассистента и ваше следующее сообщение пользователя в тот же массив
messagesи отправьте снова. Этот API не хранит состояние; полный диалог находится в вашей полезной нагрузке запроса.
Поскольку структура запросов у всех моделей одинакова, код, написанный для claude-opus-5-5@aws, можно перенести на другую модель, изменив только строку model. Держите это поле в одном месте кода — например, в конфигурационном значении или переменной окружения — и не хардкодьте его в нескольких файлах.
Небольшое пояснение по именованию: платформа документирует эту модель как claude-opus-5-5@aws. Используйте именно эту строку. Опечатки, лишние пробелы или пропущенный суффикс приведут к ошибке класса «модель не найдена», а не к полезному предупреждению.
Получение учётных данных и аутентификация
Перед вызовом API вам нужен API-ключ из вашей учётной записи HiAPI. Относитесь к этому ключу как к секрету: храните его в переменной окружения или менеджере секретов платформы, никогда не помещайте в систему контроля версий и никогда — в клиентский код, отправляемый в браузер.
HiAPI аутентифицирует запросы с помощью bearer token в заголовке Authorization:
export HIAPI_API_KEY="your-api-key-here"
Каждый запрос должен содержать:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Несколько практических правил помогут избежать большинства сбоев аутентификации:
- Сохраняйте буквальный префикс
Bearerс последующим пробелом, а затем ключ. Отсутствие префикса или пробела — распространённая ошибка при копировании и вставке. - Не заключайте ключ в кавычки внутри значения заголовка.
- Если вы ротируете ключ, обновите переменную окружения и перезапустите процесс — долго работающие worker-ы часто кэшируют старое значение.
- При вставке ключа в файл
.envпроверяйте наличие завершающих пробелов или символов новой строки; некоторые загрузчики не удаляют их автоматически.
Если ключ отсутствует или имеет неверный формат, вы получите ошибку аутентификации (класса 401), а не ошибку модели, поэтому её легко отличить от последующих проблем. Как только запрос успешно прошёл аутентификацию, тот же заголовок можно использовать для потоковой передачи, вызова инструментов и всех остальных режимов из этого руководства — отдельные учётные данные для каждой функции не нужны.
Для серверного кода загружайте ключ один раз при запуске и передавайте его в общий клиент или небольшую функцию-обёртку. Это концентрирует секрет в одном месте и делает переключение между учётными данными разработки и продакшена тривиальным.
Создание рабочего запроса с помощью curl
Ниже приведён полный рабочий запрос. Замените ключ-заполнитель на свой или сначала выполните export из предыдущего раздела, чтобы shell подставил значение.
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-5-5@aws",
"messages": [
{
"role": "user",
"content": "Объясните в трёх предложениях, почему идемпотентные POST-эндпоинты важны для платёжного API."
}
]
}'
Разберём по частям:
- Эндпоинт —
POST https://api.hiapi.ai/v1/chat/completions. - Заголовки — bearer token и тип содержимого JSON. Оба обязательны.
model— точный идентификаторclaude-opus-5-5@aws.messages— массив объектов с role и content. Последнее сообщение пользователя — это то, на что модель должна ответить.- Полезная нагрузка —
-dотправляет сырой JSON, поэтому обработка кавычек важна. В shell заключайте всё тело запроса в одинарные кавычки, а для ключей JSON используйте двойные кавычки.
Ответ — это JSON с массивом choices. Сгенерированный текст находится в choices[0].message.content и сопровождается информацией об использовании (счётчики токенов), чтобы вы могли отслеживать расход. Использование в ответе оплачивается по токенам; актуальные тарифы смотрите на панели цен на сайте.
Типичные настройки:
{
"model": "claude-opus-5-5@aws",
"max_tokens": 512,
"temperature": 0.2,
"messages": [
{"role": "system", "content": "Вы — лаконичный технический редактор."},
{"role": "user", "content": "Суммируйте вышеуказанное тело запроса одной строкой."}
]
}
Используйте max_tokens, чтобы ограничить неконтролируемую генерацию, temperature — чтобы управлять многословностью и разбросом, а сообщение system — чтобы задать поведение один раз на весь диалог. Сообщение system следует размещать в том же массиве messages, перед ходами пользователя.
Тот же запрос на Python
Версия на Python использует стандартную библиотеку urllib, поэтому фрагмент кода запускается без установки чего-либо. Если вы предпочитаете клиентскую библиотеку, структура запроса остаётся точно такой же — отличается только способ передачи.
import json
import os
import urllib.request
API_URL = "https://api.hiapi.ai/v1/chat/completions"
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "claude-opus-5-5@aws"
def ask(user_message: str, system_message: str | None = None) -> str:
messages = []
if system_message:
messages.append({"role": "system", "content": system_message})
messages.append({"role": "user", "content": user_message})
payload = json.dumps({
"model": MODEL,
"messages": messages,
}).encode("utf-8")
request = urllib.request.Request(
API_URL,
data=payload,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
body = json.loads(response.read().decode("utf-8"))
return body["choices"][0]["message"]["content"]
if __name__ == "__main__":
print(ask("Поприветствуйте ровно пятью словами."))
Почему эту структуру стоит сохранить:
MODELиAPI_URL— константы уровня модуля, поэтому смена модели или эндпоинта требует изменения одной строки.- Ключ берётся из окружения; функция никогда не принимает сырой секрет в качестве аргумента.
- Логика разбора изолирована в конце, поэтому вы можете заменить
urllibнаhttpxилиrequests, не меняя способ построения диалога.
Чтобы продолжить многоходовой диалог, перед повторной отправкой добавьте ответ ассистента и следующее сообщение пользователя в messages. Позволяйте массиву расти, пока не достигнете лимита контекста, затем суммируйте ранние ходы в одно system-сообщение, чтобы уложиться в бюджет. Использование в ответе считается по токенам; актуальные тарифы опубликованы на панели цен на сайте.
Потоковая передача для интерактивных сценариев
Для чат-интерфейсов и длительной генерации потоковая передача отправляет частичное содержимое по мере появления вывода, а не ждёт полного ответа. Тело запроса остаётся неизменным, кроме одного поля:
{
"model": "claude-opus-5-5@aws",
"messages": [{"role": "user", "content": "Напишите короткую запись в журнале изменений для библиотеки, которая только что перешла на потоковую передачу."}],
"stream": true
}
При stream: true эндпоинт отвечает событиями, отправляемыми сервером (server-sent events): каждый блок — это строка с префиксом data: , а поток завершается финальной строкой-терминатором. Большинство блоков содержат в массиве choices delta с фрагментом текста, а не полное сообщение.
При использовании curl уберите эффект тишины -sS, чтобы видеть, как вывод поступает постепенно:
curl -N https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"claude-opus-5-5@aws","stream":true,"messages":[{"role":"user","content":"Медленно посчитайте до пяти."}]}'
Флаг -N отключает буферизацию, чтобы вы видели блоки по мере их поступления. В Python читайте ответ построчно:
with urllib.request.urlopen(request) as response:
for raw_line in response:
line = raw_line.decode("utf-8").strip()
if not line.startswith("data: "):
continue
data = line[len("data: "):]
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0].get("delta", {})
text = delta.get("content")
if text:
print(text, end="", flush=True)
Практические советы:
- Всегда обрабатывайте терминатор
[DONE]и пустые/keep-alive строки; не предполагайте, что каждая строка — это JSON. - Никогда не блокируйте UI-поток на всём потоке — добавляйте delta в буфер по мере поступления.
- Если клиент отключается, закройте ответ, чтобы освободить восходящую генерацию.
- Потоковая передача не меняет способ расчёта использования; последний блок обычно несёт метаданные об использовании. Оплата считается по выходным токенам; актуальные тарифы смотрите на панели цен на сайте.
Добавление вызова инструментов в диалог
Использование инструментов позволяет модели запрашивать структурированные действия из вашего кода, а не только генерировать текст. В запрос добавляется массив tools; в диалог — сообщение ассистента с tool_calls и сообщения с role: "tool", содержащие результаты.
Определите параметры инструмента с помощью JSON Schema:
{
"model": "claude-opus-5-5@aws",
"messages": [
{"role": "user", "content": "Какая сейчас погода в Лиссабоне?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Возвращает текущую погоду для города.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Название города, например Lisbon"}
},
"required": ["city"]
}
}
}
]
}
Модель может вернуть сообщение с tool_calls вместо финального текста. Каждый элемент указывает имя функции и несёт аргументы в виде JSON-строки. Ваша задача — выполнить эту функцию для своей системы, а затем добавить результат:
- Добавьте сообщение ассистента с
tool_callsвmessagesкак есть. - Для каждого вызова добавьте сообщение с
role: "tool", соответствующимtool_call_idиз сообщения ассистента иcontent, установленным в сериализованный результат. - Снова отправьте запрос с тем же массивом
tools. Затем модель сгенерирует естественно-языковой ответ на основе ваших результатов.
Меры защиты, которые стоит ввести как можно раньше:
- Проверяйте аргументы — перед выполнением любых действий проверяйте аргументы по схеме — никогда не передавайте вывод модели напрямую в shell или запрос к базе данных.
- Ограничивайте циклы. Установите верхний предел числа раундов вызова инструментов (обычно от трёх до пяти), чтобы модель, постоянно запрашивающая вызовы, не зациклилась бесконечно.
- Возвращайте ошибки как результат инструмента. Если функция завершается с ошибкой, отправьте короткую строку ошибки с соответствующим
tool_call_id; тогда модель сможет повторить попытку или объяснить причину сбоя, а не застрять. - Делайте описания инструментов точными. Расплывчатые описания приводят к неверному выбору инструмента гораздо чаще, чем ошибки в параметрах.
Определения инструментов оцениваются вместе с запросом и учитываются в вашем использовании токенов. Актуальные тарифы опубликованы на панели цен на сайте.
Что делать дальше
Начните с минимального вызова curl, перенесите его в функцию-обёртку на Python, а затем добавляйте потоковую передачу и инструменты только если это нужно для вашего сценария. Строка модели claude-opus-5-5@aws всегда остаётся неизменной — всё остальное — это поля в полезной нагрузке запроса.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий