Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Perus-URL ja ensimmäinen pyyntö

Oppitunti 1 / 14 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Hallinta-API: erillinen ohjaustaso
  2. Perus-URL
  3. Hallinta-API:n todennus
  4. Päätepisteiden rakenne
  5. Ensimmäinen hallintapyyntösi
  6. Keskeiset asiat

Hallinta-API: erillinen ohjaustaso

xAI:n hallinta-API (Management API) on erillinen järjestelmä verrattuna siihen päättely-API:hon (inference API), jota käytät kehoteiden lähettämiseen Grokille. Sen avulla hallinnoit resurssejasi: luot ja hallitset API-avaimia, määrität laskutusta, seuraat käyttöä ja valvot tiimisi oikeuksia. Kaikki tämä hallinta tapahtuu omistetun URL-osoitteen kautta.

Perus-URL

Tämä erottelu ei ole vain toteutusyksityiskohta: se heijastaa näiden kahden API:n välistä perustavanlaatuista eroa. Toinen kuluttaa tokeneita ja suorittaa malleja; toinen hallinnoi, laskuttaa ja myöntää käyttöoikeuksia. Niiden pitäminen eri verkkotunnuksilla ja eri avainsarjoilla takaa, että varastettu sovellusavain ei voi koskaan luoda muita avaimia eikä lukea laskutustietojasi.

https://management-api.x.ai

Älä sekoita tätä osoitteeseen https://api.x.ai, joka on tarkoitettu päättelypyynnöille (keskustelun täydennykset, upotukset jne.). Kaikki hallintapyynnöt – avaimet, laskutus, analytiikka – kulkevat osoitteen management-api.x.ai kautta.

2
Erilliset URL-osoitteet
REST
Vakioarkkitehtuuri
JSON
Vaihtomuoto
Bearer
Todennus

Hallinta-API:n todennus

Todennusmekanismi on sama – Bearer-tokeni Authorization-otsakkeessa – mutta itse avain on eri. Tämä on yleisin sekaannus aloittelijoilla, ja se johtaa täysin epäselvään 401-virheeseen: virheilmoituksessa ei ole mitään viitettä siitä, että olisit yksinkertaisesti esittänyt oikean avaimen väärälle API:lle.

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

Tämä validointipyyntö (GET /auth/management-keys/validation) antaa sinun varmistaa, että hallinta-avaimesi on voimassa ja aktiivinen. Se on yksinkertaisin lähtökohta konfiguraatiosi testaamiseen.

Hallinta-avain vs. päättelyavain

  • Hallinta-avain: myöntää pääsyn management-api.x.ai-päätepisteisiin (hallinto, laskutus, analytiikka)
  • Päättelyavain: myöntää pääsyn api.x.ai-päätepisteisiin (keskustelu, upotukset, kuvat)

Molemmat avaintyypit luodaan xAI-konsolista, mutta niiden laajuus (scope) eroaa. Päättelyavain ei pääse hallintapäätepisteisiin, eikä päinvastoin.

Päätepisteiden rakenne

Hallinta-API:n päätepisteet noudattavat loogista organisaatiota:

  • /auth/teams/{teamId}/api-keys – API-avainten hallinta
  • /auth/api-keys/{apiKeyId} – toiminnot tietylle avaimelle
  • /auth/teams/{teamId}/models – käytettävissä olevat mallit
  • /auth/teams/{teamId}/endpoints – käytettävissä olevat ACL-päätepisteet
  • /v1/billing/teams/{teamId}/ – laskutus ja analytiikka

Parametri teamId on tiimisi tunniste xAI-konsolissa, ja se jäsentelee lähes kaikkia päätepisteitä. Jokaisella tiimillä on omat avaimensa, kiintiönsä ja laskutusasetuksensa, mikä tekee siitä luontevan eristysyksikön: kahden projektin erottaminen kahteen tiimiin erottaa myös niiden budjetit ja käyttöoikeudet ilman lisäkonfiguraatiota.

Ensimmäinen hallintapyyntösi

Tässä on täydellinen esimerkki konfiguraatiosi validointiin:

# Määritä hallinta-avaimesi
export MANAGEMENT_API_KEY="xai-mgmt-..."

# Validoi avain
curl -s https://management-api.x.ai/auth/management-keys/validation \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool

Jos vastaus sisältää tiimi- ja avaintietosi, konfiguraatiosi toimii. Jos saat 401-virheen, varmista, että käytät hallinta-avainta (et päättelyavainta).

Keskeiset asiat

  • Hallinta-API käyttää osoitetta https://management-api.x.ai, joka on erillinen osoitteesta https://api.x.ai
  • Todennus käyttää Bearer-tokenia Authorization-otsakkeessa
  • Hallinta-avaimilla ja päättelyavaimilla on erilliset laajuudet
  • Päätepiste GET /auth/management-keys/validation antaa sinun testata konfiguraatiosi
  • Kaikki hallintapäätepisteet on organisoitu teamId:n ympärille