Премини към основното съдържание
Български— Изберете език
Меню

Базов URL и първа заявка

Урок 1 от 14 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Управленският API: Отделна равнина за управление
  2. Базов URL
  3. Удостоверяване в Управленския API
  4. Структура на крайните точки
  5. Вашата първа заявка за управление
  6. Ключови изводи

Управленският API: Отделна равнина за управление

Управленският API на xAI е отделен от API за изводи (inference), който използвате за изпращане на подкани към Grok. Той Ви позволява да администрирате ресурсите си: създаване и управление на API ключове, конфигуриране на фактурирането, мониторинг на използването и контрол на достъпа на Вашия екип. Цялото това администриране се извършва чрез специализиран URL адрес.

Базов URL

Това разделение не е просто детайл от реализацията: то отразява фундаментална разлика между двата API. Единият консумира токени и изпълнява модели; другият администрира, фактурира и предоставя разрешения. Поддържането им в два различни домейна и с два комплекта ключове гарантира, че откраднат ключ за приложение никога не може да създава други ключове или да чете информацията Ви за фактуриране.

https://management-api.x.ai

Не бъркайте този адрес с https://api.x.ai, който е URL за заявки за изводи (завършване на чат, вграждания и др.). Всички заявки за управление – ключове, фактуриране, аналитика – минават през management-api.x.ai.

2
Различни URL адреси
REST
Стандартна архитектура
JSON
Формат за обмен
Bearer
Удостоверяване

Удостоверяване в Управленския API

Механизмът за удостоверяване е идентичен – Bearer токен в хедъра Authorization, но самият ключ не е същият. Това е най-честото объркване при започване на работа и то води до напълно неясна грешка 401: нищо в съобщението за грешка не показва, че просто сте представили правилния ключ на грешния API.

curl https://management-api.x.ai/auth/management-keys/validation \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Тази заявка за валидиране (GET /auth/management-keys/validation) Ви позволява да проверите дали Вашият ключ за управление е валиден и активен. Това е най-простата входна точка за тестване на Вашата конфигурация.

Ключ за управление срещу Ключ за изводи

  • Ключ за управление: предоставя достъп до крайните точки (endpoints) на management-api.x.ai (администриране, фактуриране, аналитика)
  • Ключ за изводи: предоставя достъп до крайните точки на api.x.ai (чат, вграждания, изображения)

И двата типа ключове се генерират от конзолата на xAI, но техните обхвати (scopes) се различават. Ключ за изводи не може да достига крайни точки за управление и обратно.

Структура на крайните точки

Крайните точки на Управленския API следват логическа организация:

  • /auth/teams/{teamId}/api-keys — управление на API ключове
  • /auth/api-keys/{apiKeyId} — операции върху конкретен ключ
  • /auth/teams/{teamId}/models — достъпни модели
  • /auth/teams/{teamId}/endpoints — налични крайни точки за ACL
  • /v1/billing/teams/{teamId}/ — фактуриране и аналитика

Параметърът teamId е идентификаторът на Вашия екип в конзолата на xAI и той структурира почти всички крайни точки. Всеки екип има свои собствени ключове, квоти и настройки за фактуриране – което го прави естествената единица за изолация: разделянето на два проекта в два екипа също така разделя техните бюджети и достъп, без нужда от допълнителна конфигурация.

Вашата първа заявка за управление

Ето един пълен пример за валидиране на Вашата конфигурация:

# Дефинирайте Вашия ключ за управление
export MANAGEMENT_API_KEY="xai-mgmt-..."

# Валидирайте ключа
curl -s https://management-api.x.ai/auth/management-keys/validation \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool

Ако отговорът съдържа информация за Вашия екип и ключ, конфигурацията Ви работи правилно. Ако получите грешка 401, проверете дали използвате ключ за управление (а не ключ за изводи).

Ключови изводи

  • Управленският API използва https://management-api.x.ai, който е различен от https://api.x.ai
  • Удостоверяването използва Bearer токен в хедъра Authorization
  • Ключовете за управление и ключовете за изводи имат отделни обхвати
  • Крайната точка GET /auth/management-keys/validation Ви позволява да тествате конфигурацията си
  • Всички крайни точки за управление са организирани около teamId