Как использовать API grok-4.6: cURL, Python и рабочий запрос

grok-4.6 — это дообученная на рассуждения чат-модель, доступная через API hiapi. В отличие от моделей изображений и видео hiapi, она не использует асинхронный конвейер /v1/tasks — это синхронный, совместимый с OpenAI интерфейс чат-дополнений, поэтому вы сразу получаете обычный HTTP-ответ (или поток SSE) без опроса. В этой статье сначала показан минимальный рабочий запрос, а затем разобраны части, которые действительно нужны в продакшене: потоковый вывод, вызов инструментов, режим JSON и обработка ошибок.

Что вам понадобится

• API-ключ hiapi. Если у вас его ещё нет, получите его в консоли — каждый запрос ниже требует его в заголовке Authorization: Bearer sk-....
• Любой HTTP-клиент. В примерах используются curl и Python-библиотека requests; структура JSON одинакова независимо от языка.
• SDK не требуется. Формат запросов и ответов grok-4.6 очень близок к соглашениям OpenAI для чат-дополнений, поэтому инструменты, совместимые с OpenAI, обычно работают, но hiapi предоставляет собственный эндпоинт чат-дополнений, а не проприетарный — направьте клиент на https://api.hiapi.ai/v1/chat/completions и используйте голый идентификатор модели grok-4.6.

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

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "user", "content": "Объясни одним предложением, для чего нужен фильтр Калмана."}
    ]
  }'

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

{
  "id": "b6c018d3-218e-9b06-aa12-5afc02e21b5c",
  "object": "chat.completion",
  "model": "grok-4.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Фильтр Калмана оценивает истинное состояние системы во времени, объединяя зашумлённые измерения с моделью прогноза и взвешивая их по соответствующим неопределённостям."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 31,
    "total_tokens": 55
  }
}

Текст ответа находится в choices[0].message.content, как и в любом чат-API в стиле OpenAI.

Вот тот же вызов на Python с использованием requests:

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [
            {"role": "user", "content": "Объясни одним предложением, для чего нужен фильтр Калмана."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

Параметры рассуждения grok-4.6

grok-4.6 — это модель рассуждения: прежде чем написать окончательный ответ, она тратит дополнительные токены на «размышление», и эти токены рассуждения тарифицируются как выходные токены (актуальные тарифы см. на странице цен). Вы можете управлять объёмом размышлений через reasoning_effort, принимающий одно из значений low, medium, high или xhigh (если опустить, API по умолчанию использует high):

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Поздоровайся пятью словами."}],
    "reasoning_effort": "low"
  }'

Нестриминговый ответ предоставляет траекторию рассуждений модели в message.reasoning_content отдельно от окончательного message.content. Для коротких задач с низкой задержкой снижайте до low или medium; для многошаговых задач high или xhigh обменивают задержку и токены на более качественный ответ.

Потоковый ответ

Установите "stream": true, чтобы читать ответ в виде Server-Sent Events, вместо ожидания полного дополнения:

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Посчитай от 1 до 5."}],
    "stream": true
  }'

Каждая строка представляет собой блок data: {...}. Токены рассуждения передаются потоком через choices[0].delta.reasoning_content, затем токены ответа — через choices[0].delta.content, а поток завершается литералом data: [DONE]:

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"reasoning_content":"Перечисляю"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1, 2"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

В Python requests может итерировать поток построчно:

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [{"role": "user", "content": "Посчитай от 1 до 5."}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        payload = line[len(b"data: "):]
        if payload == b"[DONE]":
            break
        chunk = json.loads(payload)
        delta = chunk["choices"][0]["delta"]
        if "content" in delta:
            print(delta["content"], end="", flush=True)

Вызов инструментов

grok-4.6 поддерживает вызов функций в стиле OpenAI: передайте массив tools и через tool_choice: "auto" позвольте модели самой решать, когда вызывать инструмент.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Какая погода в Токио?"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Получить текущую погоду в городе",
          "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

Когда модель решает вызвать инструмент, finish_reason возвращается как "tool_calls", а аргументы приходят в виде JSON-строки, которую вам нужно разобрать самостоятельно:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_...",
            "type": "function",
            "function": {"name": "get_weather", "arguments": "{\"city\":\"Tokyo\"}"}
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Выполните свою функцию, затем добавьте в messages сообщение с role: "tool" (содержащее результат выполнения и соответствующий tool_call_id) и отправьте диалог обратно, чтобы получить окончательный ответ на естественном языке.

Режим JSON

Если вы хотите разбирать ответ без кругового обмена вызовами инструментов, установите response_format:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "system", "content": "Ответь JSON-объектом с двумя ключами \"city\" и \"country\"."},
      {"role": "user", "content": "Где находится Эйфелева башня?"}
    ],
    "response_format": {"type": "json_object"}
  }'

message.content возвращается в виде JSON-строки (по-прежнему внутри обычного конверта чат-дополнения), и вы разбираете её на своей стороне с помощью json.loads(...). Обязательно указывайте в подсказке, чтобы модель действительно генерировала JSON — response_format ограничивает формат вывода, но не создаёт схему за вас.

Практики для продакшена

• Обрабатывайте задокументированные коды ошибок. Неверный или отсутствующий ключ возвращает HTTP 401 с телом ответа {"error":{"code":"permission_denied","message":"...","request_id":"...","type":"hiapi_error"}}. Недостаток средств возвращает 402; неверный идентификатор модели или неверный формат параметров возвращает 400. Сначала проверяйте код состояния и записывайте request_id из тела ответа с ошибкой — именно эта информация понадобится вам, если придётся сообщить о проблеме.
• Применяйте повторные попытки с экспоненциальной задержкой для 429 и 503. hiapi применяет ограничения скорости на уровне аккаунта; 429 означает, что вы превысили лимит, 503 — что модель временно недоступна. Для обоих случаев подходит повторная попытка с ограниченной экспоненциальной задержкой (например, 1 с, 2 с, 4 с, затем отказ после нескольких попыток), а не плотный цикл.
• Задавайте тайм-ауты запросов. При интенсивности рассуждений high или xhigh выполнение заметно дольше, чем при low; задавайте тайм-аут клиента в зависимости от используемого уровня интенсивности, а не единой глобальной константой.
• В любых сценариях, ориентированных на пользователя, предпочитайте потоковый вывод. Нестриминговые вызовы блокируются до готовности полного ответа (включая все токены рассуждения); потоковый вывод позволяет немедленно доставить первые токены в ваш UI и показать состояние «думает», когда приращения reasoning_content приходят раньше окончательного ответа.
• Не хардкодьте ключи. Загружайте их из переменных окружения или менеджера секретов и никогда не читайте из системы контроля версий — приведённые выше примеры именно поэтому читают из $HIAPI_API_KEY / os.environ["HIAPI_API_KEY"].

Полный справочник параметров (включая каждое поле, которое принимает grok-4.6) см. на странице модели и в документации grok-4.6.

Часто задаваемые вопросы

Совместим ли grok-4.6 на hiapi с OpenAI SDK? Структура запросов и ответов следует соглашениям OpenAI для чат-дополнений (messages, choices[0].message.content, потоковые приращения, вызов инструментов), поэтому большинство инструментов, совместимых с OpenAI и позволяющих переопределить базовый URL и идентификатор модели, должны работать. Направьте базовый URL на https://api.hiapi.ai/v1 и используйте grok-4.6 в качестве идентификатора модели.

Почему мой ответ медленнее, чем у других моделей? grok-4.6 перед ответом тратит токены на внутреннее рассуждение, и эти токены тарифицируются как выходные. Для вызовов, чувствительных к задержке, снизьте reasoning_effort до low или medium либо переключитесь на потоковый вывод, чтобы не ждать весь ответ целиком.

Что означает reasoning_content и можно ли скрыть его от пользователя? Это промежуточная траектория рассуждений модели, возвращаемая отдельно от content (при потоковой передаче — в виде delta.reasoning_content). Вы вполне можете не отображать его в UI — окончательным ответом является только content.

Я получил 401 и permission_denied — что пошло не так? Ваш заголовок Authorization отсутствует, имеет неверный формат, либо ключ недействителен или отозван. Перепроверьте, что вы отправляете Authorization: Bearer sk-... и используете действительный ключ из консоли.

Могу ли я одновременно использовать вызов функций grok-4.6 и режим JSON в одном запросе? tools/tool_choice и response_format — независимые параметры, их можно задавать одновременно, но если модель решит вызвать инструмент, finish_reason этого раунда будет "tool_calls", а message.content может быть пустым — сначала обработайте вызов инструмента, а затем в последующем раунде запросите окончательный ответ в формате JSON.

Как контролировать затраты? Токены рассуждения учитываются как выходные токены, поэтому стоимость зависит от reasoning_effort и длины ответа. Перед запуском высоконагруженных задач ознакомьтесь с текущими тарифами за токен на странице цен.