HiAPI
Блог

Руководство

Как вызвать claude-opus-5-5@aws через HiAPI API: руководство по curl и Python

Nov 12, 2026
Обложка с мятно-зелёными растровыми точками, плотность которых постепенно меняется на почти чёрном фоне с акцентами глубокого бирюзового цвета.
На этой странице

Как выглядит работа с claude-opus-5-5@aws через HiAPI

HiAPI предоставляет единый HTTP-интерфейс для множества моделей. Вам не нужно отдельно настраивать аккаунты, SDK и хранилища учётных данных для каждого провайдера — достаточно обращаться к HiAPI с одним и тем же форматом запроса и выбирать нужную модель через идентификатор модели. В этом руководстве такой идентификатор — claude-opus-5-5@aws; суффикс @aws является частью имени модели, а не отдельным полем, и должен передаваться как есть.

Жизненный цикл одного запроса выглядит так:

  1. Аутентификация — отправьте ваш API-ключ HiAPI в заголовке Authorization в виде bearer token.
  2. Отправка чат-подобной полезной нагрузки — JSON-тело запроса с полем model и массивом messages, где каждое сообщение содержит role (system, user или assistant) и content.
  3. Получение JSON-ответа — ответ ассистента появляется в массиве choices ответа вместе с метаданными об использовании.
  4. Продолжение диалога — добавьте сообщение ассистента и ваше следующее сообщение пользователя в тот же массив 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-строки. Ваша задача — выполнить эту функцию для своей системы, а затем добавить результат:

  1. Добавьте сообщение ассистента с tool_calls в messages как есть.
  2. Для каждого вызова добавьте сообщение с role: "tool", соответствующим tool_call_id из сообщения ассистента и content, установленным в сериализованный результат.
  3. Снова отправьте запрос с тем же массивом tools. Затем модель сгенерирует естественно-языковой ответ на основе ваших результатов.

Меры защиты, которые стоит ввести как можно раньше:

  • Проверяйте аргументы — перед выполнением любых действий проверяйте аргументы по схеме — никогда не передавайте вывод модели напрямую в shell или запрос к базе данных.
  • Ограничивайте циклы. Установите верхний предел числа раундов вызова инструментов (обычно от трёх до пяти), чтобы модель, постоянно запрашивающая вызовы, не зациклилась бесконечно.
  • Возвращайте ошибки как результат инструмента. Если функция завершается с ошибкой, отправьте короткую строку ошибки с соответствующим tool_call_id; тогда модель сможет повторить попытку или объяснить причину сбоя, а не застрять.
  • Делайте описания инструментов точными. Расплывчатые описания приводят к неверному выбору инструмента гораздо чаще, чем ошибки в параметрах.

Определения инструментов оцениваются вместе с запросом и учитываются в вашем использовании токенов. Актуальные тарифы опубликованы на панели цен на сайте.

Что делать дальше

Начните с минимального вызова curl, перенесите его в функцию-обёртку на Python, а затем добавляйте потоковую передачу и инструменты только если это нужно для вашего сценария. Строка модели claude-opus-5-5@aws всегда остаётся неизменной — всё остальное — это поля в полезной нагрузке запроса.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API