Премини към основното съдържание
Български— Изберете език
Меню

Създаване и конфигуриране на API ключ

Урок 2 от 14 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Защо да създавате ключове чрез API
  2. Крайна точка за създаване
  3. Пълен пример с curl
  4. Препоръчителни стратегии за ACL
  5. Налични крайни точки за ACL
  6. Ключови изводи

Защо да създавате ключове чрез API

Ръчното създаване на ключ отнема тридесет секунди – точно затова се нуждаете от автоматизация. Тъй като процесът е бърз, го извършвате без да се замисляте: липсва конвенция за именуване, няма лимити на заявките, просто използвате джокър, за да „действате бързо“. Шест месеца по-късно никой не знае кой ключ какво прави.

Използването на API Ви принуждава да именувате, обхватите и ограничавате всеки ключ, тъй като те са параметри на скрипта. Съгласуваността престава да бъде дисциплина, която трябва да поддържате, и се превръща в свойство на кода. Можете да автоматизирате създаването на ключове за Вашите среди (dev, staging, production), да прилагате детайлни списъци за контрол на достъпа (ACLs) и да дефинирате лимити на скоростта – всичко това директно във Вашите скриптове за внедряване или инструменти за инфраструктура.

Крайна точка за създаване

За да създадете API ключ, изпратете POST заявка до следната крайна точка:

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

Тяло на заявката

{
  "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"
}

Детайлни параметри

name (задължителен): четим идентификатор за Вашия ключ. Изберете описателно име, което указва употребата (prod-backend, staging-chatbot, dev-john). Това име се появява в конзолата и в логовете за употреба.

acls (задължителен): списък с разрешения, предоставени на този ключ. Налични са два формата:

  • api-key:endpoint:[endpoint] – ограничава достъпните крайни точки (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[model] – ограничава използваемите модели (grok-4.20-0309-reasoning, grok-4.3 и др.)

Символът * действа като джокер: api-key:endpoint:* разрешава всички крайни точки, api-key:model:* – всички модели. Запазете това за локална разработка. В производствена среда джокерът означава, че компрометиран ключ дава достъп до всичко, което екипът Ви може да прави – включително до най-скъпите модели, които приложението Ви може никога да не използва.

qps (по желание): заявки в секунда – максимален брой заявки за секунда.

qpm (по желание): заявки в минута – максимален брой заявки за минута.

tpm (по желание): токени в минута – максимален брой обработени токени за минута.

expireTime (по желание): дата на изтичане във формат ISO 8601. Ключът ще бъде автоматично деактивиран на тази дата.

Пълен пример с 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"
  }'

Отговорът съдържа секретния ключ, който никога повече няма да бъде показан. Това правило има практическо следствие, което трябва да предвидите преди изпълнението на скрипта, а не след него: ако създавате ключове в цикъл, съхранението трябва да се извърши в същото действие. Ключ, загубен между създаването и регистрацията, не може да бъде възстановен – трябва да го изтриете и да започнете отначало. Запишете го в хранилище за тайни (Vault, AWS Secrets Manager), а не в стандартния изход на терминала, където ще остане в историята Ви.

Препоръчителни стратегии за ACL

Ключ за разработка (широк обхват)

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

Идеален за локална разработка: достъпът е широк, защото не знаете предварително какво ще тествате, но лимитите на скоростта остават ниски. Това е правилният компромис – безкраен цикъл, написан по грешка в петък вечер, ще Ви струва няколко цента, вместо няколкостотин евро.

Продукционен ключ (ограничен)

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

В производствена среда правилото се обръща: започнете от това, което приложението действително прави, и разрешете само него. Въпросът, който винаги трябва да си задавате при писането на ACL, е един и същ – ако този ключ изтече утре, какво може да направи трета страна с него? Ключ, ограничен до chat на един модел и капнат на десет заявки в секунда, дава кратък отговор.

Временен ключ (с изтичащ срок)

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

Автоматичното изтичане решава проблема, който никой не обработва: ключовете, които хората забравят да изтрият. POC, демонстрация, временен изпълнител – във всички тези случаи expireTime гарантира, че достъпът се изключва сам. Това е единственият надежден начин за поддържане на чист инвентар, защото не разчита на ничия памет.

Налични крайни точки за ACL

За да видите крайните точки, които можете да използвате в ACLs, консултирайте:

GET /auth/teams/{teamId}/endpoints

Наличните крайни точки са: chat, embed, image, models, sample, tokenize, documents. Този списък може да се променя с времето, затова го проверявайте редовно.

Ключови изводи

  • Създаването на ключове става чрез POST /auth/teams/{teamId}/api-keys
  • ACLs следват формата api-key:endpoint:[name] или api-key:model:[name]
  • Джокерът * предоставя пълен достъп до всички крайни точки или модели
  • Секретният ключ се показва само веднъж при създаване – запазете го незабавно
  • Винаги дефинирайте лимити на скоростта (qps, qpm, tpm), съобразени с употребата
  • Използвайте expireTime за временни ключове