Adres bazowy i pierwsze żądanie
Na tej stronie
Management API: Oddzielna płaszczyzna sterowania
Management API od xAI to osobny byt w porównaniu z API wnioskowania, którego używasz do wysyłania promptów do Groka. Pozwala Ci zarządzać zasobami: tworzyć i administrować kluczami API, konfigurować rozliczenia, monitorować zużycie oraz kontrolować dostęp swojego zespołu. Cała ta administracja odbywa się poprzez dedykowany adres URL.
Adres bazowy
Ten podział to nie tylko szczegół implementacyjny – odzwierciedla on fundamentalną różnicę między tymi dwoma interfejsami. Jeden zużywa tokeny i uruchamia modele, drugi zajmuje się administracją, rozliczeniami i przyznawaniem uprawnień. Umieszczenie ich na dwóch różnych domenach i używanie dwóch odrębnych zestawów kluczy gwarantuje, że skradziony klucz aplikacyjny nigdy nie pozwoli na utworzenie innych kluczy ani odczytanie informacji o Twoich rozliczeniach.
https://management-api.x.ai
Nie myl tego adresu z https://api.x.ai, który służy do wywołań wnioskowania (uzupełniania czatu, embeddingi itp.). Wszystkie żądania związane z zarządzaniem – kluczami, rozliczeniami, analityką – przechodzą przez management-api.x.ai.
Uwierzytelnianie w Management API
Mechanizm uwierzytelniania jest identyczny – token Bearer w nagłówku Authorization – ale sam klucz jest inny. To najczęstsze źródło nieporozumień na początku pracy, które skutkuje całkowicie niezrozumiałym błędem 401: w komunikacie błędu nie ma żadnej wskazówki, że po prostu przedstawiłeś właściwy klucz niewłaściwemu API.
curl https://management-api.x.ai/auth/management-keys/validation \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
To żądanie walidacyjne (GET /auth/management-keys/validation) pozwala zweryfikować, czy Twój klucz zarządzania jest ważny i aktywny. To najprostszy punkt wejścia do przetestowania Twojej konfiguracji.
Klucz zarządzania a klucz wnioskowania
- Klucz zarządzania: zapewnia dostęp do endpointów
management-api.x.ai(administracja, rozliczenia, analityka) - Klucz wnioskowania: zapewnia dostęp do endpointów
api.x.ai(czat, embeddingi, obrazy)
Oba typy kluczy są generowane w konsoli xAI, ale ich zakresy działania się różnią. Klucz wnioskowania nie może uzyskać dostępu do endpointów zarządzania i odwrotnie.
Struktura endpointów
Endpointy Management API są logicznie zorganizowane:
/auth/teams/{teamId}/api-keys— zarządzanie kluczami API/auth/api-keys/{apiKeyId}— operacje na konkretnym kluczu/auth/teams/{teamId}/models— dostępne modele/auth/teams/{teamId}/endpoints— dostępne endpointy ACL/v1/billing/teams/{teamId}/— rozliczenia i analityka
Parametr teamId to identyfikator Twojego zespołu w konsoli xAI i stanowi on podstawę struktury niemal wszystkich endpointów. Każdy zespół ma własne klucze, limity i ustawienia rozliczeniowe, co czyni go naturalną jednostką izolacji: rozdzielanie dwóch projektów na dwa zespoły automatycznie rozdziela ich budżety i dostęp, bez potrzeby dodatkowej konfiguracji.
Twoje pierwsze żądanie zarządzania
Oto kompletny przykład walidacji Twojej konfiguracji:
# Zdefiniuj swój klucz zarządzania
export MANAGEMENT_API_KEY="xai-mgmt-..."
# Zweryfikuj klucz
curl -s https://management-api.x.ai/auth/management-keys/validation \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool
Jeśli odpowiedź zawiera informacje o Twoim zespole i kluczu, konfiguracja działa poprawnie. Jeśli otrzymasz błąd 401, sprawdź, czy używasz klucza zarządzania, a nie klucza wnioskowania.
Kluczowe wnioski
- Management API używa adresu
https://management-api.x.ai, który jest inny niżhttps://api.x.ai - Uwierzytelnianie odbywa się za pomocą tokena Bearer w nagłówku
Authorization - Klucze zarządzania i klucze wnioskowania mają odrębne zakresy uprawnień
- Endpoint
GET /auth/management-keys/validationpozwala przetestować konfigurację - Wszystkie endpointy zarządzania są zorganizowane wokół parametru
teamId