Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Sukurti ir sukonfigūruoti API raktą

Paskaita 2 iš 14 Atnaujinta 2026 m. liepos 29 d. Kūrėjas
Šiame puslapyje
  1. Kodėl kurti raktus per API
  2. Kūrimo galinis punktas
  3. Pilnas pavyzdys naudojant curl
  4. Rekomenduojamos ACL strategijos
  5. Galimi ACL galiniai punktai
  6. Svarbiausi punktai

Kodėl kurti raktus per API

Rankinis rakto kūrimas trunka trisdešimt sekundžių – būtent todėl tau reikia automatizavimo. Kadangi tai greitai, darai tai negalvodamas: jokių pavadinimų konvencijų, jokių užklausų ribų, tik bendrasis „kad būtų greičiau“. Po šešių mėnesių niekas nebežino, ką kuris raktas veikia.

Naudojant API, tenka kiekvienam raktui suteikti pavadinimą, apibrėžti jo taikymo sritį ir nustatyti ribas, nes tai yra skripto parametrai. Nuoseklumas nustoja būti disciplina, kurią turiu palaikyti, ir tampa kodo savybe. Gali automatizuoti raktų kūrimą savo aplinkoms (kūrimo, testavimo, gamybos), taikyti tikslias prieigos kontrolės sąrašų (ACL) taisykles ir apibrėžti užklausų ribas – visa tai tiesiai savo diegimo skriptuose arba infrastruktūros įrankiuose.

Kūrimo galinis punktas

Norėdamas sukurti API raktą, siųsk POST užklausą į šį galinį punktą:

POST /auth/teams/{teamId}/api-keys

Užklausos kūnas

{
  "name": "ma-cle-production",
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 10,
  "qpm": 100,
  "tpm": 1000000,
  "expireTime": "2026-12-31T23:59:59Z"
}

Išsamūs parametrai

name (būtina): skaitomas tavo rakto identifikatorius. Pasirinkite aprašomąjį pavadinimą, nurodantį naudojimo paskirtį (prod-backend, staging-chatbot, dev-john). Šis pavadinimas rodomas konsolėje ir naudojimo žurnaluose.

acls (būtina): šiam raktui suteiktų leidimų sąrašas. Galimi du formatai:

  • api-key:endpoint:[galinis_punktas] – riboja pasiekiamus galinius punktus (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[modelis] – riboja naudojamus modelius (grok-4.20-0309-reasoning, grok-4.3 ir kt.)

Simbolis * veikia kaip bendrasis ženklas: api-key:endpoint:* leidžia naudoti visus galinius punktus, api-key:model:* – visus modelius. Palik tai tik vietinei kūrimo aplinkai. Gamyboje bendrasis ženklas reiškia, kad pažeistas raktas suteikia prieigą viskam, ką gali daryti tavo komanda – įskaitant brangiausius modelius, kurių tavo programėlė gali niekada ir nenaudoti.

qps (nebūtina): užklausos per sekundę – didžiausias užklausų skaičius per sekundę.

qpm (nebūtina): užklausos per minutę – didžiausias užklausų skaičius per minutę.

tpm (nebūtina): žetonai per minutę – didžiausias per minutę apdorotų žetonų skaičius.

expireTime (nebūtina): galiojimo pabaigos data ISO 8601 formatu. Šią datą pasiekus raktas bus automatiškai išjungtas.

Pilnas pavyzdys naudojant curl

curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v2",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning",
      "api-key:model:grok-4.3"
    ],
    "qps": 20,
    "qpm": 500,
    "tpm": 2000000,
    "expireTime": "2027-06-30T23:59:59Z"
  }'

Atsakyme gaunamas slaptasis raktas, kuris daugiau niekada nebus parodytas. Ši taisyklė turi praktinę pasekmę, kurią turi numatyti prieš paleisdamas skriptą, o ne po to: jei kuri raktus cikle, saugojimas turi vykti tuo pačiu metu. Raktas, prarastas tarp kūrimo ir registracijos, nėra atkuriamas – tenka jį ištrinti ir pradėti iš naujo. Įrašyk jį į saugyklą (Vault, AWS Secrets Manager), o ne į terminalo standartinę išvestį, kur jis atsidurs tavo istorijoje.

Rekomenduojamos ACL strategijos

Kūrimo raktas (platus)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 5,
  "qpm": 50
}

Idealu vietinei kūrimo aplinkai: prieiga plati, nes iš anksto nežinai, ką bandysi, tačiau užklausų ribos lieka mažos. Tai tinkamas kompromisas – penktadienio vakarą per klaidą parašytas begalinis ciklas kainuos kelis centus, o ne kelis šimtus eurų.

Gamybos raktas (ribotas)

{
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 50,
  "qpm": 2000,
  "tpm": 5000000
}

Gamyboje taisyklė apverčiama: pradėk nuo to, ką programėlė iš tikrųjų daro, ir leisk tik tai. Rašydamas ACL visada klausk savęs to paties – jei šis raktas nutekės rytoj, ką trečioji šalis galės su juo nuveikti? Raktas, apribotas pokalbiams viename modelyje ir ribojamas iki dešimties užklausų per sekundę, duoda trumpą atsakymą.

Laikinas raktas (galiojantis ribotą laiką)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "expireTime": "2026-04-10T00:00:00Z"
}

Automatinis galiojimo pabaigos nustatymas išsprendžia problemą, kurios niekas nesprendžia: žmonės pamiršta ištrinti raktus. POC, demonstracija, laikinas rangovas – visais šiais atvejais expireTime garantuoja, kad prieiga išsijungs pati. Tai vienintelis patikimas būdas palaikyti švarią inventorių, nes jis nepriklauso nuo niekieno atminties.

Galimi ACL galiniai punktai

Norėdamas pamatyti galinius punktus, kuriuos gali naudoti ACL, kreipkis į:

GET /auth/teams/{teamId}/endpoints

Galimi galiniai punktai: chat, embed, image, models, sample, tokenize, documents. Šis sąrašas laikui bėgant gali keistis, todėl tikrink jį reguliariai.

Svarbiausi punktai

  • Raktai kuriami naudojant POST /auth/teams/{teamId}/api-keys
  • ACL laikosi formato api-key:endpoint:[pavadinimas] arba api-key:model:[pavadinimas]
  • Bendrasis ženklas * suteikia visišką prieigą visiems galiniams punktams arba modeliams
  • Slaptasis raktas rodomas tik vieną kartą kūrimo metu – išsaugok jį nedelsiant
  • Visada apibrėžk naudojimui tinkamas užklausų ribas (qps, qpm, tpm)
  • Laikiniems raktams naudok expireTime