Сложность подключения Grok API обычно не в написании запроса, а в трёх вещах: соответствуют ли друг другу ключ и адрес, какой endpoint использовать и откуда скопировать имя модели. Если всё сделать правильно, первый вызов запускается за несколько минут; если ошибиться, чаще всего вы увидите 401, 404 или model not found.
Статья опирается на документацию xAI и последовательно разбирает: аккаунт и ключ, Base URL, имена моделей, curl, Python, потоковый вывод и вызов функций, разбор ошибок, чек-лист миграции. Цены и доступные модели меняются — перед подключением сверьтесь со страницей Models у xAI и страницей цены на модели.
Примечание: xAI и Grok — товарные знаки их правообладателей, OpenAI — товарный знак своего правообладателя. Статья носит технический характер.
1. Сначала выберите путь: консоль xAI или совместимый шлюз
У ключа Grok API два распространённых источника: консоль xAI и шлюзы, предоставляющие OpenAI-совместимый вход. Формат запросов близок, но аккаунт, оплата и Base URL различаются; ключи нельзя смешивать.
| Параметр | xAI напрямую | ZSQH AI Gateway |
|---|---|---|
| Консоль | console.x.ai | ai.zhongshangqihang.com |
| Base URL | https://api.x.ai/v1 |
https://ai.zhongshangqihang.com/v1 |
| Оплата | Способы, поддерживаемые xAI | Пополнение в юанях, условия — на сайте |
| Кому подходит | Стабильный доступ и зарубежная оплата | Доступ из Китая, единый счёт, переключение моделей |
Сначала выберите путь, потом создавайте ключ. Если вставить ключ xAI в адрес шлюза или наоборот, обычно получите 401. Регистрация в шлюзе — здесь; нужен ли шлюз, зависит от вашей сети, оплаты и требований к счетам.
2. Шесть шагов создания ключа
- Зарегистрируйтесь и войдите в консоль. Прямой путь — console.x.ai; путь через шлюз начинается со страницы регистрации.
- Настройте биллинг или пополните баланс. Без доступной квоты ключ может создаться, но вызовы будут падать.
- Перейдите на страницу API Keys, создайте ключ и укажите проект и окружение, например
prod-qa-2026-10. - Сразу скопируйте полный ключ и сохраните его в серверной переменной окружения или менеджере секретов. Многие консоли показывают ключ только при создании.
- Задайте минимально необходимые права: лимит, IP или права команды; то, чего нет в консоли, не обязательно.
- Проверьте минимальным запросом, что ключ, Base URL и имя модели совпадают.
Не записывайте ключ во фронтенд-код, Git-репозиторий или переписку. Создавайте отдельные ключи для теста и продакшена, чтобы при ротации не пострадал весь бизнес.
3. Base URL и endpoint: только до /v1
Base URL xAI — https://api.x.ai/v1. Два замечания: Base URL заканчивается на /v1, не добавляйте /chat/completions вручную; конкретный endpoint определяется SDK или путём запроса.
Сейчас xAI рекомендует POST /v1/responses (Responses API). OpenAI-совместимый POST /v1/chat/completions по-прежнему работает, но помечен как legacy, а новые возможности сначала появляются в Responses API. Новым проектам стоит сразу использовать Responses API; существующий код Chat Completions может продолжать работать, но нужно понимать, что это уже не основной путь.
Минимальный запрос curl с единой аутентификацией Authorization: Bearer:
export XAI_API_KEY="ваш-ключ"
curl https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.7",
"input": "Объясни в трёх предложениях, что такое API-шлюз.",
"store": false
}'
Параметр store определяет, сохраняются ли запрос и ответ на сервере. Документация xAI указывает, что Responses по умолчанию хранит данные 30 дней. Для чувствительного контента лучше явно задать store: false и учитывать, что после отключения нельзя продолжать диалог через previous_response_id.
4. Как заполнять имя модели: копируйте ID, не угадывайте
Имя модели — идентификатор API, а не рекламное название на сайте. Страница Models перечисляет доступные ID, длину контекста и тарифный уровень. Ниже несколько примеров из документации октября 2026 года — только для формата:
| ID модели | Контекст | Типичное применение |
|---|---|---|
grok-4.7 |
500k | Универсальные вопросы, код, агенты |
grok-4.3 |
1M | Длинные документы и диалоги |
grok-4.20-0309-reasoning |
1M | Задачи с явным рассуждением |
grok-build-0.1 |
256k | Сборка и кодирование в рабочих процессах |
Модели добавляются и выводятся из эксплуатации, а в названиях бывают суффиксы с датой. Перед запуском копируйте имя со страницы Models или со страницы цены на модели, не пишите по памяти. Модели с -reasoning обычно выдают процесс рассуждения; задержка и структура затрат у них отличаются — сначала проверьте на малом трафике.
5. Первый вызов на Python
xAI предоставляет SDK, а также поддерживает OpenAI SDK. Команде с существующим кодом OpenAI достаточно изменить base_url и api_key:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["XAI_API_KEY"],
base_url="https://api.x.ai/v1",
)
response = client.responses.create(
model="grok-4.7",
input="Объясни в трёх предложениях, что такое API-шлюз.",
store=False,
)
print(response.output_text)
output_text — удобное свойство SDK для простого текста. Если нужны рассуждения, вызовы инструментов или ссылки, перебирайте response.output и смотрите на type; не предполагайте, что текст всегда лежит по фиксированному индексу.
6. Потоковый вывод и вызов функций
Потоковый вывод использует SSE: в запросе задаётся "stream": true, клиент читает приращения по частям. Документация предупреждает, что генерация рассуждающих моделей может занимать долго; при потоковом выводе увеличивайте тайм-аут клиента, чтобы соединение не закрылось раньше времени. Ниже — вызов совместимого endpoint через OpenAI SDK:
stream = client.chat.completions.create(
model="grok-4.7",
messages=[{"role": "user", "content": "Объясни в трёх предложениях, что такое SSE."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
Вызов функций состоит из пяти шагов: опишите имя, назначение и JSON Schema инструмента; поместите инструмент в запрос; модель вернёт function_call; вы выполните функцию локально; результат вернётся модели для продолжения. В Responses API определение инструмента плоское: ключевые поля — type: "function", name, description и parameters.
Две детали, которые часто упускают: в потоковом режиме аргументы вызова функции могут прийти целиком, а не посимвольно; серверные инструменты поиска могут тарифицироваться отдельно по числу вызовов — сверяйтесь со страницей цен. Чем больше инструментов и чем расплывчатее описания, тем выше вероятность, что модель выберет не тот инструмент; сначала сократите количество и уточните параметры.
7. Частые ошибки: сначала смотрите на код состояния
| Код | Частая причина | Что делать |
|---|---|---|
| 401 | Ключ не передан, неверен или не соответствует Base URL | Проверьте заголовок Authorization и совместимость адреса |
| 403 | У аккаунта или ключа нет прав, либо ограничения региона и условий | Проверьте права и статус аккаунта в консоли |
| 404 | Неверный путь или имя модели | Сверьте /v1/responses и ID модели |
| 400 / 422 | Неверный формат полей запроса | Сверьте поля с API Reference |
| 429 | Превышена частота или параллелизм | Повторяйте с экспоненциальной задержкой, снизьте параллелизм |
| Тайм-аут | Долгая генерация рассуждающей модели или медленная сеть | Увеличьте тайм-аут, включите потоковый режим, логируйте время |
Недостаток баланса не всегда проявляется как 429; точные коды и сообщения — в консоли и документации. Порядок разбора: сначала код состояния, затем текст ошибки, и только потом промпт. Даже лучший промпт не исправит неверный Base URL.
8. Чек-лист перед запуском
- Поместите ключ в серверную переменную окружения и убедитесь, что он не попадает во фронтенд-бандл и логи.
- Зафиксируйте Base URL и запретите вручную склеивать endpoint в бизнес-коде.
- Создайте таблицу соответствия моделей: старая модель, новая, контекст и тарифный уровень.
- Новые проекты — на
/v1/responses; старые с Chat Completions пометьте как legacy и запланируйте миграцию. - Унифицируйте тайм-ауты, повторы и отмену для потокового и обычного режимов.
- Для 429 и 5xx задайте экспоненциальную задержку без бесконечных повторов.
- Логируйте ID запроса, модель, расход токенов и задержку — для сверки и диагностики.
- Сначала включите на некритичной функции и наблюдайте неделю, затем расширяйте.
Частые вопросы
Какой Base URL указывать для Grok API?
Напрямую у xAI — https://api.x.ai/v1; для шлюза — адрес из его консоли. Только до /v1, без конкретного endpoint.
Почему OpenAI SDK может вызывать Grok?
xAI предоставляет OpenAI-совместимую структуру запросов, особенно Chat Completions; Responses API также вызывается через responses.create OpenAI SDK. Достаточно направить base_url на xAI, но имя модели и часть параметров всё равно берутся из документации xAI.
Grok API и OpenAI API — одно и то же?
Нет. Это сервисы разных компаний, совместимые лишь по форме интерфейса. Ключи, биллинг, модели и политика обработки данных различаются; смешивать их нельзя.
Обязательно ли использовать Responses API?
Новым проектам рекомендуется. xAI пометил Chat Completions как legacy, новые возможности появляются сначала в Responses API; существующие системы можно мигрировать по плану, без переключения за одну ночь.
Как команде из Китая подключиться стабильнее?
Сначала определите, в чём проблема: сеть, оплата или комплаенс. Если только доступ и расчёты — оцените OpenAI-совместимый шлюз; если данные не могут покидать внутреннюю сеть — рассматривайте приватное развёртывание. Решение зависит от ваших ограничений.
Итог
Подключение Grok API можно свести к одной фразе: выберите правильный источник ключа, указывайте Base URL только до /v1, копируйте имя модели со страницы xAI, а новые проекты сразу делайте на Responses API. Остальное — потоковый вывод, функции и обработка ошибок — детали этой основной цепочки.
Для единого управления моделями и счетами начните со страницы регистрации; модели и тарификация — на странице цены на модели.
Читайте также:
