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

Management API: Avainten ja laskutuksen hallinta

Oppitunti 12 / 14 Päivitetty 28. heinäkuuta 2026 Keskitasoinen
Tällä sivulla
  1. Hallitse tiliäsi ilman konsolia
  2. Avainten luominen ja kierrätys
  3. Seuraa ja hallitse laskutusta
  4. Seuraa kulutustasi oikealla tarkkuudella
  5. Keskeiset asiat

Hallitse tiliäsi ilman konsolia

xAI Management API on REST-rajapinta, joka on omistettu yritystilisi hallintaan. Kun Inference API (api.x.ai) kutsuu malleja, Management API (management-api.x.ai) hallinnoi resurssejasi. Ero saattaa vaikuttaa pieneltä, mutta sitä se ei ole. Kaikki, mikä muuten vaatisi jonkun avaamaan verkkokonsolin ja klikkailemaan, voidaan täällä automatisoida – tehdä jäljitettäväksi, toistettavaksi ja integroitavaksi tiimiesi jo käyttämiin työkaluihin.

Avainten luominen ja kierrätys

Avainten luominen API:n kautta mahdollistaa uusien sovellusten tai ympäristöjen käyttöönoton automatisoinnin:

curl -X POST "https://management-api.x.ai/auth/teams/{teamId}/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cle-production-chatbot",
    "acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
    "qps": 10,
    "qpm": 100,
    "tpm": 1000000,
    "expireTime": "2026-12-31T23:59:59Z"
  }'

Tämän pyynnön parametrit määrittelevät avaimen käyttöoikeudet täysin:

  • name: Ihmiselle luettava tunniste avaimelle
  • acls: Luettelo käyttöoikeuksista (valtuutetut päätepisteet ja mallit)
  • qps/qpm/tpm: Nopeusrajoitukset sekunnissa, minuutissa ja tokenia minuutissa
  • expireTime: Automaattinen vanhenemispäivä

expireTime-asetuksen määrittäminen luontivaiheessa on tapa, joka säästää sinua eniten vaivalta pitkällä aikavälillä: kolmen kuukauden pilotointia varten myönnetty avain vanhenee itsestään sen sijaan, että se jäisi ikuisesti voimaan konfiguraatiotiedostoon, jota kukaan ei enää lue.

Säännöllinen avainten kierrätys noudattaa samaa tietoturvahygieniaa. Erillinen päätepiste generoi uuden salaisen avaimen ja mitätöi vanhan:

curl -X POST "https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

Varoitus: vanha salainen avain mitätöityy välittömästi ja pysyvästi. Valmistele uuden arvon käyttöönotto salaisuuksien hallintajärjestelmässäsi ennen komennon suorittamista, älä koskaan sen jälkeen. Kolme vain luku -päätepistettä täydentää kokonaisuuden: GET /auth/teams/{teamId}/api-keys listaa kaikki tiimin avaimet, GET /auth/api-keys/{apiKeyId}/propagation varmistaa, että avain on levitetty kaikille solmuille, ja GET /auth/teams/{teamId}/models listaa käytettävissä olevat mallit niiden hinnoittelun kera. Toinen näistä on se, jota tarkistat heti kierrätyksen jälkeen, kun sovellus palauttaa edelleen todennusvirheitä etkä ole varma, johtuuko virhe sovellusbugista vai pelkästä levitysviiveestä.

Seuraa ja hallitse laskutusta

Laskutustietojen hakeminen tapahtuu omalla päätepisteellään:

curl "https://management-api.x.ai/v1/billing/teams/{teamId}/billing-info" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

Haat laskuhistorian kausisuodatuksella, tässä esimerkissä maaliskuulta 2026:

curl "https://management-api.x.ai/v1/billing/teams/{teamId}/invoices?billingCycle.year=2026&billingCycle.month=3" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

Jokaiseen laskuun liittyy tila, joka on joko PENDING, PAID, FAILED tai WILL_NEVER_BE_CHARGED. FAILED-tilan havaitseminen valvontajärjestelmissäsi on huomattavasti parempi vaihtoehto kuin tiedon saaminen häiriöstä palvelukatkon kautta maanantaiaamuna.

Estääksesi budjetin ylitykset, määritä kuukausittainen katto:

curl -X POST "https://management-api.x.ai/v1/billing/teams/{teamId}/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthlyLimit": 5000}'

Jos toimit ennakkomaksulla, tarkista saldo samalla tavalla:

# Check balance
curl "https://management-api.x.ai/v1/billing/teams/{teamId}/prepaid/balance" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

Muista, että ennakkomaksuhyvitykset ovat palautuskelvottomia, ellei laki toisin vaadi. Mitoita ostosi usean viikon aikana havaitun kulutuksen perusteella, äläkä optimististen kasvuprognoosien pohjalta.

Seuraa kulutustasi oikealla tarkkuudella

Analytiikkapäätepiste mahdollistaa käytön seurannan hienojakoisesti:

curl -X POST "https://management-api.x.ai/v1/billing/teams/{teamId}/usage" \
  -H "Authorization: Bearer $MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "analyticsRequest": {
      "timeRange": {
        "startTime": "2026-03-01 00:00:00",
        "endTime": "2026-04-01 00:00:00",
        "timezone": "UTC"
      },
      "timeUnit": "DAY",
      "values": [{"name": "tokens", "aggregation": "SUM"}],
      "groupBy": ["model"]
    }
  }'

Tämä pyyntö palauttaa päivittäisen token-kulutuksen mallikohtaisesti jaettuna maaliskuulta. Muuttamalla timeUnit-parametria voit vaihtaa näkymän kuukausitasosta minuuttitasoon: mahdollisia arvoja ovat MONTH, CALENDAR_WEEK, DAY, HOUR, QUARTER_HOUR ja MINUTE. Aggregointifunktiot ulottuvat kauas pelkkien summien yli sisältäen SUM, AVG, MIN, MAX, P50, P90, P99 ja COUNT. Persentiilit kuvaavat kuormitusta tehokkaasti, koska keskiarvot tasoittavat juuri niitä piikkejä, jotka määrittävät todellisen kapasiteettitarpeesi.

Management API löytää näin paikkansa työkaluketjussasi. Luot avaimia Terraformilla tai Pulumilla aivan kuten tietokantoja, CI/CD-putkesi luo väliaikaisia avaimia testiympäristöille ja poistaa ne suorituksen lopussa, valvontaskriptit hälyttävät ennen kulutuskaton saavuttamista, ja sisäiset kojelautasi näyttävät kulutustiedot ilman, että kenenkään tarvitsee viedä CSV-tiedostoja ulos joka maanantai.

Keskeiset asiat

  • Management API osoitteessa management-api.x.ai hallinnoi avaimia, laskutusta ja mittareita
  • Avainten kierrätys mitätöi vanhan salaisen avaimen pysyvästi
  • Kulutuskatot suojaavat budjetin ylityksiltä
  • Käyttöanalytiikka tarjoaa tarkkuuden minuutista kuukauteen
  • Integroi Management API infrastruktuurityökaluihisi hallinnon automatisoimiseksi