Руководство
Как вызвать kimi-k3.1-pro-highspeed через HiAPI API: примеры на curl и Python
На этой странице
Что такое 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 к продакшен-вызову — в основном работа с конфигурацией. Начните с непоточного вызова, добавьте потоковую передачу, когда появится интерактивный путь, и пусть обёртка повторных попыток поглощает сбои, которые вы не можете предотвратить.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий