Как использовать kimi-k3 через hiapi API: curl, Python и рабочие примеры запросов

Что вы создадите

kimi-k3 — это диалоговая модель с возможностью рассуждения, доступная на hiapi через стандартный OpenAI-совместимый эндпоинт /v1/chat/completions — без опроса асинхронных задач и без загрузки изображений. Это руководство проведёт вас с нуля через рабочий вызов с помощью curl и Python, а затем объяснит две вещи, на которых легко споткнуться в продакшене: токены рассуждения отнимают бюджет вашего max_tokens и потоковый вывод.

Предварительные требования: ключ API hiapi. Если его нет, получите его в консоли — каждый запрос ниже аутентифицируется через Authorization: Bearer sk-<your-key>.

Минимальный рабочий пример

kimi-k3 — текстовая модель, поэтому она не проходит через очередь задач /v1/tasks, которую hiapi использует для моделей изображений/видео — это прямой синхронный вызов чат-завершения.

curl

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
    ],
    "max_tokens": 300
  }'

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [
            {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
        ],
        "max_tokens": 300,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])

Успешный ответ выглядит так:

{
  "id": "chatcmpl-fb762e7481bd4442abb1d8ed3892b4f5",
  "model": "FW-Kimi-K3",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need answer user: \"Reply with exactly the word OK.\" ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 95,
    "completion_tokens": 52,
    "total_tokens": 147,
    "completion_tokens_details": {"reasoning_tokens": 38}
  }
}

Итоговый ответ находится в choices[0].message.content. В запросе используется «голый» ID модели kimi-k3 — hiapi выполняет сопоставление внутренне (в поле model тела ответа будет возвращён внутренний тег, например FW-Kimi-K3, — это ожидаемое поведение).

Единственная ловушка: токены рассуждения и max_tokens

kimi-k3 — это модель рассуждения: перед генерацией итогового content она записывает цепочку рассуждений в message.reasoning_content, и оба используют один и тот же бюджет max_tokens. Если max_tokens задан слишком малым, модель может потратить весь бюджет на рассуждение и вернуть finish_reason: "length" с пустым полем content:

{
  "choices": [{
    "message": {"content": "", "reasoning_content": "The user is asking me to say \"OK\""},
    "finish_reason": "length"
  }]
}

Это не баг — просто рассуждение исчерпало пространство до достижения итогового ответа. Есть два способа справиться:

• Оставьте достаточно запаса. Для коротких фактических ответов max_tokens в диапазоне 200–300 обычно хватает на рассуждение и ответ. Для более длинной генерации увеличьте бюджет соответственно.
• Проверяйте finish_reason. Если возвращается "length" и content пуст, повторите запрос с увеличенным max_tokens и не считайте пустую строку итоговым ответом.

Потоковый вывод

Установите "stream": true, чтобы получать события, отправляемые сервером (SSE), вместо ожидания полного ответа. Сначала блоки данных несут инкрементальный delta.reasoning_content, а после того как модель начнёт писать итоговый ответ, — delta.content:

import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [{"role": "user", "content": "Count to 3."}],
        "max_tokens": 200,
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if line and line.startswith(b"data: ") and line != b"data: [DONE]":
            print(line.decode("utf-8"))

Если вы создаёте интерфейс чата, отображайте в потоке только delta.content — большинство приложений скрывают delta.reasoning_content за переключателем «размышление» или сворачивают его, а не показывают встроенно.

Замечания по работе в продакшене

• Обработка ошибок. Недействительный или отсутствующий ключ возвращает HTTP 401 и структурированное тело ответа:

  {"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}
  

  Записывайте request_id — он понадобится службе поддержки, если вы откроете тикет.
• Повторные попытки. Чат-завершения синхронны, поэтому нет ни ID задачи для опроса, ни обратного вызова для регистрации (этот режим подходит для асинхронных моделей изображений/видео hiapi, но не для текста). При тайм-ауте или 5xx просто повторите запрос; поскольку сервер не ставит никаких задач в очередь, это можно рассматривать как обычный идемпотентный повтор в стиле GET.
• Оплата. kimi-k3, как и другие текстовые модели на платформе, оплачивается по токенам — перед оценкой затрат при масштабировании проверьте текущие тарифы на странице цен, так как токены рассуждения засчитываются в токены завершения.

Частые вопросы

Поддерживает ли kimi-k3 потоковый вывод? Да — передайте "stream": true и читайте ответ text/event-stream, как показано выше.

Почему в моём ответе content пуст? finish_reason почти наверняка равен "length" — модель потратила весь бюджет max_tokens на reasoning_content, не дойдя до итогового ответа. Увеличьте max_tokens и повторите попытку.

Нужен ли kimi-k3 эндпоинт hiapi /v1/tasks? Нет. /v1/tasks используется для асинхронных моделей генерации изображений, видео и музыки. kimi-k3 — синхронная текстовая модель, обслуживаемая через стандартный эндпоинт /v1/chat/completions.

Могу ли я использовать OpenAI Python SDK вместо нативного requests? Да — укажите base_url SDK как https://api.hiapi.ai/v1 и передайте свой ключ hiapi как API-ключ; структура запросов/ответов совместима с OpenAI.

Какой ID модели указывать в запросе? «Голый» ID kimi-k3. В поле model тела ответа вы увидите внутренний тег вроде FW-Kimi-K3 — это ожидаемое поведение, не влияющее на оплату или поведение.