# xAI-совместимый API

Настройка клиента xAI и Grok Build для работы через CoreInfra AI Hub, поддерживаемые протоколы и особенности конвертации.

xAI-совместимый API хаба позволяет вызывать модели Grok и другие генеративные модели через хаб без VPN из клиентов xAI и Grok Build по ключу хаба.

## 1. Настройте адрес и ключ

Укажите в клиенте базовый адрес `https://hub.coreinfra.ai/xai/api/v1` и подставьте ключ хаба `sk-ci2-...` в заголовок `Authorization: Bearer`.

Проверьте OpenAI Responses через cURL:

```bash
export COREINFRA_API_KEY='sk-ci2-...'
curl https://hub.coreinfra.ai/xai/api/v1/responses \
  -H "Authorization: Bearer $COREINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"grok-4.7","input":"2 + 2"}'
```

Ожидаемый текст ответа — `4`. Для клиента OpenAI Chat Completions базовый адрес тот же.

## Отличия от API xAI

Полное описание параметров приведено в [документации xAI](https://docs.x.ai/docs/api-reference). При работе через хаб действуют следующие отличия:

* Адрес API обслуживает только API методы из таблицы ниже. Изображения, видео, Files, Batches и голосовые API xAI через него не предоставляются. WebSocket для Responses у этого адреса API не поддерживается.
* Заголовок `x-grok-model-override` и поле `inference_geo` игнорируются (модель выбирается полем `model` в теле запроса). Для моделей Grok в Responses и Chat Completions игнорируются `user`, `safety_identifier` и `service_tier`, а в Responses также отключено сохранение на стороне провайдера (`store: false`); правила для моделей других провайдеров приведены в справочниках [Responses](https://coreinfra.ru/docs/reference/xai/responses.md#differences) и [Chat Completions](https://coreinfra.ru/docs/reference/xai/chat-completions.md#differences).
* В Responses отклоняются со статус-кодом `400` параметры `background: true`, `prompt`, `conversation`, MCP с `tunnel_id` и встроенные инструменты провайдера (`code_interpreter`, `file_search`, `image_generation`, `x_search`, `code_execution`, `collections_search`, `attachment_search` и контейнерный `shell`).
* В Chat Completions отклоняются со статус-кодом `400` параметр `deferred: true` и встроенные инструменты (`code_interpreter`, `code_execution`, `file_search`, `collections_search`, `x_search`, `web_search`, `retrieval`, `builtin_function`). Используйте пользовательские функции (`type: "function"`).
* Для `/xai/api/v1/messages` действуют [отличия Anthropic-совместимого API](https://coreinfra.ru/docs/use/anthropic.md#limits).
* Входные изображения и файлы передавайте в кодировке base64. Ссылки на внешние ресурсы и `file_id` отклоняются со статус-кодом `400`.
* Когда ответ модели Grok через Responses или Chat Completions (без конвертации) содержит данные о стоимости и сумма списания рассчитана, хаб возвращает стоимость запроса в рублях в поле `usage.cost_rub`.

## Конвертация

Когда выбранная модель не поддерживает вызванный протокол напрямую (например, вызов Grok через `/xai/api/v1/messages` или вызов моделей Anthropic и Google через `/xai/api/v1/responses`), хаб конвертирует запрос и ответ на своей стороне:

* В Responses при конвертации не поддерживаются `previous_response_id`, `conversation` и `item_reference` (возвращается ошибка со статус-кодом `400` — передавайте историю в `input`).
* В Chat Completions при конвертации формируется один вариант ответа (`n: 1`) и не конвертируются `logprobs`, `top_logprobs` и `logit_bias`. Подробности приведены в [справочнике xAI API](https://coreinfra.ru/docs/reference/xai.md).

## Что доступно

Доступны следующие API методы относительно `https://hub.coreinfra.ai/xai/api/v1`:

| Метод  | Путь                | Назначение и справочник                                                                |
| ------ | ------------------- | -------------------------------------------------------------------------------------- |
| `GET`  | `/models`           | [Каталог моделей клиента](https://coreinfra.ru/docs/reference/xai/models.md)           |
| `POST` | `/responses`        | [OpenAI Responses](https://coreinfra.ru/docs/reference/xai/responses.md)               |
| `POST` | `/chat/completions` | [OpenAI Chat Completions](https://coreinfra.ru/docs/reference/xai/chat-completions.md) |
| `POST` | `/messages`         | [Anthropic Messages](https://coreinfra.ru/docs/reference/xai/messages.md)              |
| `GET`  | `/api-key`          | [Проверка запуска клиента](https://coreinfra.ru/docs/reference/xai/api-key.md)         |

Каталог `GET /models` подготовлен для клиента Grok Build и включает генеративные модели разных провайдеров с префиксом `[CoreInfra]` и полем `api_backend`. Возможности всех моделей смотрите в [каталоге моделей](https://coreinfra.ru/docs/catalog.md), цены — на странице [«Тарифы»](https://hub.coreinfra.ai/pricing).

## Ошибки

В Responses и Chat Completions ошибки проверки параметров возвращаются в формате ошибок OpenAI, а в `/xai/api/v1/messages` — в формате ошибок Anthropic Messages; примеры приведены в [справочнике xAI API](https://coreinfra.ru/docs/reference/xai.md#errors). Общие ошибки авторизации, баланса и лимитов расходов описаны в [общем справочнике API](https://coreinfra.ru/docs/reference.md#errors) и на странице [«Лимиты и ограничения»](https://coreinfra.ru/docs/limits.md).
