Základní URL a první požadavek
Na této stránce
Správcovské API: Samostatná řídicí rovina
Správcovské API (Management API) společnosti xAI je odlišné od inferenčního API, které používáš k odesílání promptů modelu Grok. Umožňuje ti spravovat vaše zdroje: vytvářet a spravovat API klíče, konfigurovat fakturaci, sledovat využití a řídit přístup vašeho týmu. Veškerá tato administrace probíhá prostřednictvím vyhrazené URL adresy.
Základní URL
Toto oddělení není jen implementačním detailem; odráží zásadní rozdíl mezi oběma API. Jedno spotřebovává tokeny a spouští modely, zatímco druhé spravuje, fakturuje a uděluje oprávnění. Jejich umístění na dvou různých doménách a použití dvou sad klíčů zaručuje, že ukradený aplikační klíč nikdy nemůže vytvořit další klíče ani číst vaše fakturační údaje.
https://management-api.x.ai
Nepleť si tuto adresu s https://api.x.ai, což je URL pro inferenční volání (dokončování chatu, vektory/embeddings atd.). Všechny správcovské požadavky – klíče, fakturace, analytika – procházejí přes management-api.x.ai.
Ověření ve Správcovském API
Mechanismus ověření je totožný – token Bearer v hlavičce Authorization – ale samotný klíč je jiný. To je nejčastější zdroj nejasností při začátcích a výsledkem je zcela nevypovídající chyba 401: chybová zpráva nijak nenaznačuje, že jsi pouze předložil správný klíč špatnému API.
curl https://management-api.x.ai/auth/management-keys/validation \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Tento ověřovací požadavek (GET /auth/management-keys/validation) ti umožní ověřit, zda je tvůj správcovský klíč platný a aktivní. Je to nejjednodušší vstupní bod pro otestování tvé konfigurace.
Správcovský klíč versus inferenční klíč
- Správcovský klíč: uděluje přístup k endpointům
management-api.x.ai(administrace, fakturace, analytika) - Inferenční klíč: uděluje přístup k endpointům
api.x.ai(chat, vektory/embeddings, obrázky)
Oba typy klíčů se generují v konzoli xAI, ale jejich rozsahy (scopes) se liší. Inferenční klíč nemůže přistupovat ke správcovským endpointům a naopak.
Struktura endpointů
Endpointy Správcovského API následují logickou organizaci:
/auth/teams/{teamId}/api-keys— správa API klíčů/auth/api-keys/{apiKeyId}— operace s konkrétním klíčem/auth/teams/{teamId}/models— dostupné modely/auth/teams/{teamId}/endpoints— dostupné ACL endpointy/v1/billing/teams/{teamId}/— fakturace a analytika
Parametr teamId je identifikátor tvého týmu v konzoli xAI a strukturuje téměř všechny endpointy. Každý tým má své vlastní klíče, kvóty a nastavení fakturace – což z něj činí přirozenou jednotku izolace: oddělení dvou projektů do dvou týmů také oddělí jejich rozpočty a přístupy bez jakékoli další konfigurace.
Tvůj první správcovský požadavek
Zde je kompletní příklad pro ověření tvé konfigurace:
# Definuj svůj správcovský klíč
export MANAGEMENT_API_KEY="xai-mgmt-..."
# Ověř klíč
curl -s https://management-api.x.ai/auth/management-keys/validation \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool
Pokud odpověď obsahuje informace o tvém týmu a klíči, tvoje konfigurace funguje. Pokud získáš chybu 401, ověř, zda používáš správcovský klíč (nikoli inferenční klíč).
Klíčové poznatky
- Správcovské API používá
https://management-api.x.ai, což je odlišné odhttps://api.x.ai - Ověření používá token Bearer v hlavičce
Authorization - Správcovské klíče a inferenční klíče mají oddělené rozsahy
- Endpoint
GET /auth/management-keys/validationumožňuje otestovat tvou konfiguraci - Všechny správcovské endpointy jsou organizovány kolem
teamId