Подключение Grok API само по себе несложное. Сложности обычно возникают в трёх местах: откуда взять ключ, как записать Base URL и соответствуют ли друг другу ключ и адрес. Самый частый 401 связан не с истёкшим ключом, а с тем, что ключ одной платформы вставили в адрес другой.
Статья последовательно разбирает путь получения, создание ключа, настройку адреса, минимальный вызов, безопасность и диагностику. Имена моделей и их доступность смотрите на странице цены на модели; названия пунктов консоли могут меняться — ориентируйтесь на фактический интерфейс.
Примечание: xAI и Grok — товарные знаки их правообладателей. Статья носит технический характер. Интерфейсы, модели и цены могут меняться; сверяйтесь с документацией xAI и страницей цены на модели.
1. Определите, какой ключ вам нужен
У ключа Grok API два распространённых источника: консоль xAI и китайский AI-шлюз с OpenAI-совместимым входом. Оба позволяют вызывать Grok, но аккаунт, оплата и владелец счёта различаются.
| Параметр | Консоль xAI | ZSQH AI Gateway |
|---|---|---|
| Кому подходит | Есть зарубежная оплата и стабильный доступ | Китайская оплата, нужен счёт-фактура в юанях |
| Аккаунт | Аккаунт xAI | Аккаунт шлюза |
| Оплата | Способы, поддерживаемые xAI | Пополнение в юанях |
| Base URL | https://api.x.ai/v1 |
https://ai.zhongshangqihang.com/v1 |
| Счета | В долларах, курс — на вашей стороне | В юанях, единый учёт нескольких моделей |
| Набор моделей | Собственные модели xAI | Несколько моделей, подключённых в шлюзе |
Ключи двух путей не взаимозаменяемы. Официальный ключ работает только с официальным адресом, ключ шлюза — только с адресом шлюза. Сначала выберите путь, затем создавайте ключ; не смешивайте их в процессе.
2. Официальный xAI: получение ключа
- Подготовьте рабочий аккаунт xAI и проверьте его состояние, условия обслуживания и требования региона.
- Войдите в консоль xAI и найдите раздел управления API-ключами. Название пункта может зависеть от версии — ориентируйтесь на фактический интерфейс.
- По требованиям консоли настройте биллинг или предоплату. Без доступной квоты ключ создастся, но вызовы работать не будут.
- Создайте ключ и укажите в имени проект и окружение, например
prod-customer-service, — так проще проводить ротацию и аудит. - Сразу скопируйте и сохраните ключ. Большинство платформ показывает его полностью только при создании; после закрытия страницы значение может быть недоступно.
- Если консоль предлагает ограничения квоты, прав или IP, настройте их по принципу минимальных привилегий. Не оставляйте полный доступ по умолчанию.
- Проверьте минимальным запросом, что ключ, адрес и имя модели проходят.
Официальный путь подходит командам, которым нужен только Grok и у которых есть стабильная зарубежная оплата и доступ. Если оплата или сеть нестабильны, вопрос смещается с «насколько хороша модель» на «сработает ли вызов сегодня», а эксплуатационные издержки легко недооценить.
3. Шлюз: получение ключа
- Откройте ZSQH AI Gateway, зарегистрируйтесь и заполните необходимые данные о себе или компании.
- Сначала пополните небольшую сумму и проверьте оплату, зачисление и цепочку вызовов, затем добавляйте баланс под фактическое потребление.
- Создайте в консоли API-ключ, назовите его по проекту и задайте лимит расходов или оповещение.
- Запишите Base URL шлюза:
https://ai.zhongshangqihang.com/v1. - Отправьте минимальный запрос командой curl ниже и убедитесь, что вернулся код 200 и содержимое.
- После успешной проверки подключайте бизнес-код и переносите ключ в серверные переменные окружения.
Ценность шлюза не только в «доступности», но и в оплате в юанях, едином счёте, переключении моделей и управлении несколькими моделями одним ключом. Подходит ли он, зависит от способа оплаты, требований к документам и границ эксплуатационной ответственности.
4. Как записывать Base URL и endpoint
Base URL — место, где чаще всего возникают ошибки. Обычно он записывается только до /v1: SDK сам добавляет дальнейший путь. Если вы формируете полный адрес вручную, следите, чтобы путь не дублировался.
| Параметр | xAI напрямую | ZSQH AI Gateway |
|---|---|---|
| Base URL | https://api.x.ai/v1 |
https://ai.zhongshangqihang.com/v1 |
| Chat endpoint | /chat/completions |
/chat/completions |
| Заголовок аутентификации | Authorization: Bearer <Key> |
Authorization: Bearer <Key> |
| Имя модели | По официальному списку xAI | По странице цены на модели |
Типичная ошибка — записать https://api.x.ai/v1/v1/chat/completions или добавить лишний слэш в конце Base URL, а затем склеить путь. Ещё одна распространённая ошибка — использовать заголовок x-api-key в стиле Anthropic для Grok. OpenAI-совместимый вход Grok использует Bearer-аутентификацию.
5. Минимальная проверка вызова
Сначала исключите проблемы уровня кода через curl. Команда ниже отправляет короткое сообщение; ответ 200 с полем choices означает, что ключ, Base URL и имя модели совпадают:
export GROK_API_KEY="sk-ваш-ключ"
curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
-H "Authorization: Bearer $GROK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4",
"messages": [{"role": "user", "content": "Ответь только OK"}],
"max_tokens": 16
}'
Проект на Python может использовать OpenAI SDK, изменив только ключ и Base URL:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GROK_API_KEY"],
base_url="https://ai.zhongshangqihang.com/v1",
)
resp = client.chat.completions.create(
model="grok-4",
messages=[{"role": "user", "content": "Объясни в трёх предложениях, что такое API-шлюз."}],
max_tokens=256,
)
print(resp.choices[0].message.content)
Не записывайте имя модели по памяти. Разные аккаунты и шлюзы могут иметь разные наборы моделей; сверяйтесь со страницей цены на модели или списком в консоли. Ошибка в имени обычно возвращает 404 или model not found — это не проблема ключа.
6. Безопасная настройка ключа
- Храните ключ только в серверных переменных окружения или сервисе управления секретами, не в репозитории кода.
- Не включайте ключ во фронтенд-бандл, браузерные запросы или мобильный установочный пакет. Фронтенд должен обращаться только к вашему бэкенду.
- Один проект — один ключ; тест и продакшен раздельно. Так проще ограничивать расходы, проводить ротацию и искать источник потребления.
- В логах сохраняйте только первые символы или хеш ключа, а не полное значение.
- При увольнении сотрудника, завершении проекта или подозрении на утечку немедленно отзывайте ключ и создавайте новый.
- Регулярно проверяйте кривую потребления. При аномальных вызовах сначала останавливайте ключ, затем разбирайтесь, а не правьте бизнес-код.
Последствия утечки ключа — не просто «кто-то потратил ваши деньги», а одновременная потеря контроля над данными, квотами и счетами. Относитесь к ключу как к паролю базы данных: это предотвращает многие проблемы заранее.
7. Частые ошибки конфигурации
| Симптом | Частая причина | Что делать |
|---|---|---|
| 401 | Ключ не соответствует Base URL; в ключе пробел или перевод строки | Проверить источник и скопировать ключ заново |
| 404 | Дублирование пути; неверный endpoint | Base URL только до /v1, endpoint /chat/completions |
| model not found | Опечатка в имени модели или модель не активирована | Скопировать имя со страницы цен или из консоли |
| 429 | Превышены частота, параллелизм или токены | Снизить параллелизм, повторять с задержкой |
| insufficient quota | Недостаточно баланса или достигнут лимит ключа | Пополнить и проверить лимит ключа |
| Тайм-аут | Сетевая цепочка, прокси или длинный вывод | Проверить выход, задать разумные тайм-ауты соединения и чтения |
При диагностике сначала сохраните ID запроса и код состояния из ответа, затем меняйте запрос. Без кода состояния и ID приходится только угадывать.
Частые вопросы
Ключ и Base URL должны быть от одного поставщика?
Да. Официальный ключ — официальный адрес, ключ шлюза — адрес шлюза. Смешивание обычно проявляется как 401, иногда как 404 или ошибка прав.
Можно ли размещать ключ в браузере?
Не рекомендуется. Код браузера виден пользователю, ключ легко извлечь. Правильно: фронтенд вызывает ваш бэкенд, а бэкенд хранит ключ и проксирует запросы.
Может ли один ключ вызывать несколько моделей?
В режиме шлюза обычно да — достаточно указать имя модели в запросе, если модель активирована в аккаунте. Доступные модели официального аккаунта смотрите в консоли xAI.
Что делать при утечке ключа?
Немедленно отзовите или отключите ключ в консоли, создайте новый и замените его, проверьте недавнее потребление и счета. Недостаточно поменять строку в коде, оставив старый ключ действующим.
Почему только что скопированный ключ всё время даёт 401?
Проверьте лишние пробелы, переводы строк и кавычки, затем соответствие Base URL. Если ошибка остаётся, проверьте напрямую через curl, чтобы исключить настройки SDK и прокси.
Что дальше
Если нужен один вход для Grok и других моделей, создайте тестовый ключ в ZSQH AI Gateway, выполните минимальный запрос и затем подключайте бизнес. Доступность моделей и цены смотрите на странице цены на модели.
Читайте также:
