# API-ключи: как использовать

> Формат ключей sk-aiagg, заголовок Authorization Bearer, проверка ключа, ответ 401 и правила безопасного хранения.

Веб-версия: https://ai.trackly.one/developers/docs/authentication · Индекс документации: https://ai.trackly.one/llms.txt

Для любого запроса к API нужен ключ формата `sk-aiagg-...`. Он создаётся в
разделе [API-ключи](https://ai.trackly.one/account/api-keys) личного кабинета и передаётся в
заголовке `Authorization: Bearer <ключ>`. Один ключ открывает все эндпоинты:
текст, картинки, видео, озвучка. Показывается ключ ровно один раз — дальше в
базе хранится только его sha256-хеш. Неверный или отозванный ключ вернёт 401
с кодом `invalid_api_key`.

## Как выглядит ключ и где его взять?

Ключ начинается с префикса `sk-aiagg-`, дальше — случайная строка. Создание
занимает минуту: раздел [API-ключи](https://ai.trackly.one/account/api-keys) → «Создать ключ» →
скопировать значение из окна подтверждения. Восстановить ключ позже нельзя
(мы не храним оригинал), но можно создать новый.

Ключей может быть несколько — по одному на приложение или окружение. Так
проще и отзывать доступ точечно, и смотреть расход: статистика в кабинете
считается по каждому ключу отдельно.

Все ключи аккаунта тратят один общий баланс в рублях, отдельных лимитов на
ключ нет.

## Как передавать ключ в запросе?

Только через HTTP-заголовок `Authorization` со схемой `Bearer`. В query-строке
и в теле запроса ключ не принимается. OpenAI SDK ставит заголовок сам — ключ
отдаётся параметром `api_key`.

**Проверка ключа — GET /v1/models**

```bash
curl https://api.trackly.one/v1/models \
  -H "Authorization: Bearer $TRACKLY_API_KEY"
```

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-aiagg-...",  # лучше: os.environ["TRACKLY_API_KEY"]
    base_url="https://api.trackly.one/v1",
)

for model in client.models.list():
    print(model.id)
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TRACKLY_API_KEY,
  baseURL: "https://api.trackly.one/v1",
});

const models = await client.models.list();
for (const model of models.data) console.log(model.id);
```

`GET /v1/models` — удобный «пинг» для проверки связки ключ + base_url: он
бесплатный и не трогает баланс. Полное описание ответа — в
[референсе /v1/models](https://ai.trackly.one/developers/docs/reference/models-list).

## Что придёт, если ключ неверный?

401 в OpenAI-формате ошибки:

```json
{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}
```

Тот же ответ приходит для отозванного ключа и для запроса вообще без
заголовка `Authorization`. Все коды ошибок собраны в гайде
[«Ошибки API»](https://ai.trackly.one/developers/docs/errors).

## Как хранить ключ безопасно?

- Держите ключ в переменной окружения или секрет-хранилище, не в коде.
- Не коммитьте в git, не вставляйте в URL, не пишите в логи.
- Для фронтенда ключ не подходит в принципе: запросы к API должны идти
  через ваш бэкенд.

> **Важно:** Ключ засветился в репозитории или логах? Отзовите его в разделе [API-ключи](https://ai.trackly.one/account/api-keys) и создайте новый. Хеш в нашей базе не даёт восстановить ключ, но утёкший оригинал работает, пока вы его не отозвали.

## Что дальше?

Первый запрос по шагам — в [Quick start](https://ai.trackly.one/developers/docs).
Дальше — гайды по модальностям: [текст](https://ai.trackly.one/developers/docs/text),
[изображения](https://ai.trackly.one/developers/docs/images), [видео](https://ai.trackly.one/developers/docs/video),
[озвучка](https://ai.trackly.one/developers/docs/audio).