HiAPI
Блог

Руководство

Как вызвать kimi-k3.1-pro-highspeed через HiAPI API: примеры на curl и Python

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

Что такое kimi-k3.1-pro-highspeed и когда его выбирать

kimi-k3.1-pro-highspeed — одна из чат-моделей, доступных через HiAPI. Вызывается она так же, как любая другая чат-модель на платформе: отправляете набор сообщений и получаете результат дополнения. «High-speed» в названии отражает ожидаемый компромисс — выбирайте её, когда важнее задержка, а не глубина «сырого» рассуждения, когда нужны предсказуемые времена отклика, а не самый медленный и самый подробный ответ.

Поэтому она хорошо подходит для нескольких конкретных типов нагрузки:

  • Интерактивные интерфейсы — чат-UI, автодополнение и встроенные помощники, где пользователь ждёт ответа.
  • Высоконагруженные конвейеры — задачи классификации, извлечения, суммаризации и переписывания, где нужна пропускная способность, а результат одного запроса короткий.
  • Многошаговые агентные циклы — многоступенчатые процессы, в которых каждый вызов невелик, а общая задержка определяется в основном числом круговых обменов, а не каким-то отдельным вызовом.

Это не очевидный выбор, когда задача требует долгого и вдумчивого рассуждения над большим контекстом или когда генерируемый контент относится к случаям «один медленный, но качественный проход лучше множества быстрых». В таких случаях сначала протестируйте качество вывода, а затем оптимизируйте скорость — быстрый, но неверный ответ обходится дороже медленного, но правильного.

Поскольку модель доступна через единый интерфейс HiAPI, переключение на другие модели или обратно — это лишь изменение тела запроса, а не переписывание кода. Держите имя модели в конфигурации, а не хардкодьте его в месте вызова, и вы сможете проводить A/B-тестирование с другими моделями, не трогая код построения запроса.

Что «чат-модель» означает на практике

Каждый запрос устроен так: идентификатор модели, упорядоченный список сообщений (каждое сообщение содержит role и content), а также необязательные параметры, такие как stream, temperature и max_tokens. Системный промпт передаётся сообщением с role: "system". Вот и вся ментальная модель — остальная часть руководства посвящена лишь обвязке вокруг этой структуры.

Предварительные требования: учётные данные, эндпоинт и имя модели

Прежде чем писать код, убедитесь, что у вас есть все четыре пункта ниже. Большинство сбоев при первом вызове вызвано пробелами в этом списке, а не ошибками в теле запроса.

1. API-ключ

Создайте ключ в панели управления вашей учётной записи HiAPI. Относитесь к нему как к секрету: загружайте из переменной окружения, никогда не коммитьте в репозиторий и ротируйте, как только он попадёт в логи или общий блокнот.

export HIAPI_API_KEY="your-key-here"

2. Базовый URL

Эндпоинт состоит из базового URL HiAPI и пути к чат-дополнениям. Держите базовый URL в конфигурации, чтобы при его изменении не пришлось править код:

export HIAPI_BASE_URL="https://api.hiapi.ai/v1"

3. Идентификатор модели

Строка модели, которую нужно отправлять, в точности такая:

kimi-k3.1-pro-highspeed

Копируйте посимвольно. Имена моделей сопоставляются буквально — лишний пробел, другой регистр или опечатка вернут ошибку вида «модель не найдена», а не ошибку валидации другого поля, что может увести вас в неверное место при отладке.

4. Клиент, умеющий отправлять HTTPS

Для примеров curl ниже нужен только shell с установленным curl, который есть по умолчанию на macOS и в большинстве образов Linux. Для части на Python понадобятся Python 3.8+ и пакет requests:

pip install requests

Если вы предпочитаете клиент в стиле SDK, тот же эндпоинт, ключ и имя модели подойдут и там — важен формат «по проводу», поэтому в руководстве используется «сырой» HTTP, чтобы ничего не пряталось за абстракциями.

Проверка работоспособности

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

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

Ниже — полный запрос, готовый к копированию и вставке. В нём одно системное сообщение задаёт поведение, одно пользовательское — собственно запрос, а max_tokens зафиксирован, чтобы при тестировании ответ оставался коротким.

curl -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro-highspeed",
    "messages": [
      {"role": "system", "content": "Ты — немногословный технический ассистент. Отвечай в двух предложениях или меньше."},
      {"role": "user", "content": "Объясни, что такое ключ идемпотентности и почему он важен для повторных попыток."}
    ],
    "temperature": 0.3,
    "max_tokens": 200,
    "stream": false
  }'

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

  • model — идентификатор модели из предыдущего раздела. Обязателен.
  • messages — упорядоченный массив. system задаёт роль и ограничения; user несёт задачу. Порядок важен: более поздние сообщения имеют больший приоритет в управлении поведением. Для многораундовых сценариев продолжайте добавлять ходы user и assistant в тот же массив, а не склеивайте всё в одно гигантское пользовательское сообщение.
  • temperature — случайность сэмплирования. Низкие значения дают более воспроизводимый вывод, что и нужно для извлечения и классификации. Повышайте её, только когда действительно хотите вариативности.
  • max_tokens — верхняя граница генерируемого ответа. Явное задание защищает от неуправляемой генерации и делает задержку предсказуемой.
  • stream — здесь false, то есть по завершении генерации вы получите один объект JSON. В следующих разделах рассказывается о true.

Что возвращается

Ответ — это объект JSON с массивом choices. Нужный вам текст находится в choices[0].message.content. Также есть блок usage, описывающий расход токенов — логируйте его, поскольку при оплате по токенам это ваш единственный сигнал о стоимости одного запроса.

Если вы отлаживаете, прогоните вывод через форматтер, чтобы он был читаемым:

curl -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | python -m json.tool

Помещение тела запроса в payload.json и использование -d @payload.json избавляет от мучений с кавычками в shell, как только в теле становится больше нескольких полей.

Перенос запроса в Python

Цель здесь — не демонстрационный скрипт, а импортируемая функция. Сохраняйте тело запроса полностью идентичным версии на curl — те же поля, те же имена, ту же строку модели — чтобы поведение не менялось при смене инструмента.

import os
import requests

BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kimi-k3.1-pro-highspeed"


def chat(
    user_message: str,
    system_message: str = "Ты — немногословный технический ассистент.",
    temperature: float = 0.3,
    max_tokens: int = 400,
    timeout: float = 30.0,
) -> str:
    payload = {
        "model": MODEL,
        "messages": [
            {"role": "system", "content": system_message},
            {"role": "user", "content": user_message},
        ],
        "temperature": temperature,
        "max_tokens": max_tokens,
        "stream": False,
    }
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    data = response.json()
    return data["choices"][0]["message"]["content"]

Затем:

print(chat("Сформулируй одним предложением разницу между PUT и PATCH."))

Почему написано именно так

  • json=payload вместо ручного JSON — requests корректно сериализует и устанавливает тип содержимого, устраняя целый класс ошибок с кавычками.
  • Явный timeout — без него зависшее соединение может бесконечно подвесить ваш рабочий процесс. Для коротких дополнений тридцати секунд более чем достаточно; для интерактивных путей уменьшите его.
  • raise_for_status() как можно раньше — вы хотите, чтобы сбой на уровне HTTP проявился как исключение на границе вызова, а не как KeyError на choices три строки спустя.
  • Конфигурация на уровне модуля — ключ, базовый URL и модель в одном месте. Для последующего A/B-тестирования других моделей достаточно изменить одну константу.

Многораундовый диалог

Для настоящего диалога принимайте список сообщений параметром, а не строите два фиксированных сообщения:

def chat_with_history(messages: list, **kwargs) -> dict:
    payload = {"model": MODEL, "messages": messages, "stream": False, **kwargs}
    r = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=30.0,
    )
    r.raise_for_status()
    body = r.json()
    return {
        "content": body["choices"][0]["message"]["content"],
        "usage": body.get("usage"),
    }

Добавляйте ответ ассистента обратно в messages с role: "assistant", чтобы продолжить диалог, и обрезайте старые ходы по мере роста истории — контекст тарифицируется, поэтому неограниченная переписка незаметно повышает стоимость каждого запроса.

Включение и потребление потоковых ответов

Установите "stream": true, и сервер будет отправлять ответ инкрементально в виде событий, отправляемых сервером (server-sent events), а не одним объектом в конце. Для всего, что смотрит пользователь, это оправдывает дополнительную работу на клиенте: даже если общее время генерации не меняется, время до первого токена заметно снижается.

Взгляд через curl

curl -N -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro-highspeed",
    "messages": [{"role": "user", "content": "Напиши хайку о повторных попытках."}],
    "stream": true
  }'

-N отключает буферизацию вывода curl, чтобы вы действительно видели события по мере их поступления. Вы получите последовательность строк, каждая начинается с data: и несёт фрагмент JSON. Последнее событие — data: [DONE]. Считайте этот маркер признаком конца потока, а не разбираемым JSON.

Клиент на Python

import json
import requests


def stream_chat(user_message: str, timeout: float = 60.0) -> str:
    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": user_message}],
        "stream": True,
    }
    pieces = []
    with requests.post(
        f"{BASE_URL}/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        stream=True,
        timeout=timeout,
    ) as r:
        r.raise_for_status()
        for raw in r.iter_lines(decode_unicode=True):
            if not raw or not raw.startswith("data: "):
                continue
            data = raw[len("data: "):].strip()
            if data == "[DONE]":
                break
            chunk = json.loads(data)
            delta = chunk["choices"][0].get("delta", {})
            text = delta.get("content")
            if text:
                pieces.append(text)
                print(text, end="", flush=True)
    return "".join(pieces)

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

  • Склеивайте, а не заменяйте. Каждый чанк несёт только новый фрагмент. Накапливайте в списке и соединяйте один раз в конце; добавление к строке в цикле на длинных выводах даёт квадратичную сложность.
  • Защищайтесь от отсутствующего содержимого. Некоторые чанки несут только метаданные, поэтому в delta может не быть ключа content. Используйте .get() и пропускайте пустые значения.
  • Обрабатывайте неполные строки. Границы кадров могут разрывать строку. iter_lines справляется с этим, но если вы сами разбираете поток сырых байтов, буферизуйте до появления символа новой строки.
  • Задавайте тайм-аут, подходящий для потока. Общий поток может законно превысить тайм-аут короткого запроса. Используйте более длительный тайм-аут чтения или дедлайн чтения на чанк, а не отключайте тайм-аут вовсе.
  • Сохраняйте непоточный путь. Когда вам нужен только финальный текст для фоновой задачи, stream: false проще и дешевле по вычислениям. Оставьте потоковую передачу для интерактивных путей.

Разбор ошибочных ответов и проектирование повторных попыток

Повторные попытки помогают, только если сбой временный. Слепой повтор некорректного запроса лишь увеличивает масштаб ошибки. Полезное различие: ошибки, которые вы исправляете в коде, и ошибки, которые сеть или сервер устранят сами.

Классификация по кодам состояния

Не повторяйте — исправьте запрос:

  • 400 Bad Request — неверный формат JSON, отсутствует обязательное поле или недопустимое значение параметра. Прочитайте сообщение об ошибке, исправьте тело запроса и добавьте тест, чтобы это не повторилось.
  • 401 Unauthorized — ключ отсутствует, имеет неверный формат или отозван. Проверьте формат заголовка Authorization и то, что переменная окружения действительно задана в запущенном процессе, а не только в вашем shell.
  • 403 Forbidden — ключ действителен, но не разрешено выполнять это действие или использовать эту модель. Цикл повторных попыток здесь — чистый шум.
  • 404 Not Found — обычно неверный путь или неизвестный идентификатор модели. Проверьте базовый URL и точную строку модели.
  • Ошибки валидации типа 422 — тип параметра верный, но значение неприемлемо (например, temperature вне диапазона). Ограничьте значение в коде.

Повторяйте с экспоненциальной задержкой:

  • 429 Too Many Requests — вы превысили ограничение скорости. Сделайте паузу и, если ответ содержит подсказку retry-after, следуйте ей, а не угадывайте.
  • 500 / 502 / 503 / 504 — сбой на стороне сервера или шлюза. Именно здесь и нужна экспоненциальная задержка.
  • Ошибки соединения и тайм-ауты — сокет оборвался до завершения ответа. Повторите, но только если операция безопасно повторяема.

Корректно ведущий себя цикл повторных попыток

import random
import time
import requests

RETRYABLE_STATUS = {429, 500, 502, 503, 504}


def post_with_retries(url, headers, payload, max_attempts=4, base_delay=1.0):
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(url, headers=headers, json=payload, timeout=30.0)
        except (requests.ConnectionError, requests.Timeout):
            if attempt == max_attempts:
                raise
        else:
            if r.status_code < 400:
                return r.json()
            if r.status_code not in RETRYABLE_STATUS:
                raise RuntimeError(f"Не повторяемо {r.status_code}: {r.text[:200]}")
            if attempt == max_attempts:
                raise RuntimeError(f"Попытки исчерпаны, последняя {r.status_code}")
        delay = base_delay * (2 ** (attempt - 1))
        time.sleep(delay + random.uniform(0, 0.5))
    raise RuntimeError("unreachable")

Две детали, важные в продакшене

  • Джиттер не опционален. Без него группа рабочих процессов, одновременно упёршихся в ограничение скорости, будет повторять синхронно, воссоздавая пик. Случайная добавка выше разносит их во времени.
  • Ограничивайте общее время, а не только число попыток. Четыре попытки с экспоненциальной задержкой могут превысить ваш дедлайн запроса. Ограничьте число попыток так, чтобы худший случай укладывался в бюджет вызывающего кода, и передавайте оставшееся время как тайм-аут следующей попытки.

Не повторяйте потоковые запросы при частичном сбое, если только вы не решили, что делать с текстом, уже отправленным пользователю. Распространённый подход — повторять только пока ничего не показано, иначе сообщать об усечении.

Контрольный список перед запуском в продакшен

Прежде чем этот код станет критической нагрузкой, пройдите короткий список.

  • Тайм-ауты везде. У каждого запроса есть явные тайм-ауты соединения и чтения, и это значение происходит из вашего бюджета задержки, а не скопировано из примера.
  • Секреты вне репозитория. API-ключ берётся из окружения или менеджера секретов и никогда не пишется в логи. Очищайте заголовки от любого логгера запросов.
  • Имя модели в одном месте. kimi-k3.1-pro-highspeed встречается как единственная константа, так что вы можете заменить его или A/B-тестировать без поиска с заменой.
  • Ошибки классифицируются, а не глотаются. Повторяемые и не повторяемые пути в коде различаются, задержка содержит джиттер, а число попыток ограничено.
  • Логируйте использование. Записывайте расход токенов из каждого ответа вместе с задержкой и статусом. При оплате по токенам это раннее предупреждение о том, что промпт незаметно разросся.
  • Потоковый путь проверен на реальных данных. Убедитесь, что склеенный вывод для одного и того же промпта совпадает с непоточным, и что обрыв посреди потока не оставляет ваш UI в сломанном состоянии.
  • Стоимость контролируется на этапе проектирования. Всегда задавайте max_tokens, обрезайте историю диалога, длинные документы суммаризируйте перед вставкой в контекст — эти три рычага делают затраты соразмерными ценности.

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

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

Все статьи →

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

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

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