> ## Documentation Index
> Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Аутентификация

> Как получить API-ключ и передавать его в запросах

Большинство эндпоинтов `/api/v1` требуют API-ключ. Ключ привязан к аккаунту: он даёт доступ ко всему, что доступно этому аккаунту.

## Получение ключа

Ключ создаётся в веб-приложении, в разделе API-ключей на [speshu.ai/profile](https://speshu.ai/profile).

1. Откройте [speshu.ai/profile](https://speshu.ai/profile) и войдите в аккаунт.
2. Откройте раздел API-ключей и создайте ключ с понятным вам названием.
3. Сразу сохраните полное значение ключа — например, в менеджере секретов или переменной окружения.

<Warning>
  Полный ключ показывается **ровно один раз** — в момент создания. Эндпоинта, который вернул бы его целиком, не существует: в интерфейсе хранится только маскированная форма (первые и последние четыре символа). Если ключ утерян, создайте новый.
</Warning>

### Формат ключа

Ключ начинается с `sk-`, после которого идёт UUID:

```text theme={null} theme={null}
sk-019b1f2c-3d4e-7a10-9c88-2f6b0a5d1e44
```

<Note>
  Разделитель после `sk` — дефис, а не подчёркивание. Если в вашем коде или в старой документации встречалось `sk_...`, это опечатка: с таким ключом запрос будет отклонён.
</Note>

### Сколько ключей можно держать

На аккаунт допускается не больше **10 активных ключей**. Это потолок одновременно действующих ключей, а не счётчик всех выданных за всё время.

### Отзыв ключа

Отзыв действует немедленно и необратим: восстановить ключ после отзыва нельзя. Уже отозванный ключ со следующего запроса отвечает `401` с кодом `invalid_api_key`.

### Истёкший ключ

Ключ с истёкшим сроком действия API не различает: он выглядит для сервера как несуществующий. Ответ тот же — `401`, `code: invalid_api_key`, `message: "Incorrect API key provided"`.

## Передача ключа

Ключ передают одним из двух заголовков. Приоритет такой:

| Приоритет | Заголовок | Кто так отправляет |
| - | - | - |
| 1 | `X-Api-Key: sk-...` | Anthropic SDK |
| 2 | `Authorization: Bearer sk-...` | OpenAI SDK и остальные |

<Note>
  `X-Api-Key` нужен для `/api/v1/messages`: Anthropic SDK читает ключ именно из этого заголовка и не формирует `Authorization`. Все остальные SDK используют `Authorization: Bearer`.
</Note>

Если не передан ни один из заголовков, запрос проходит через браузерную сессионную cookie.

<Warning>
  Не полагайтесь на этот запасной путь. Cookie-сессия — не способ аутентификации интеграции: она не работает из серверного кода, у неё нет срока жизни, который вы контролируете, и её нельзя отозвать. В любом обращении к API отправляйте ключ явно.
</Warning>

## Примеры

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  # Authorization: Bearer — то, что использует OpenAI SDK
  curl https://speshu.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $SPESHU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Привет!"}]
    }'
  ```

  ```bash cURL theme={null} theme={null}
  # X-Api-Key — то, что использует Anthropic SDK
  curl https://speshu.ai/api/v1/messages \
    -H "X-Api-Key: $SPESHU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "max_tokens": 256,
      "messages": [{"role": "user", "content": "Привет!"}]
    }'
  ```

  ```python Python theme={null} theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://speshu.ai/api/v1",
      api_key="sk-ваш-ключ",
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Привет!"}],
  )
  ```

  ```python Python theme={null} theme={null}
  import anthropic

  client = anthropic.Anthropic(
      base_url="https://speshu.ai/api/v1",
      api_key="sk-ваш-ключ",
  )

  response = client.messages.create(
      model="gpt-4o",
      max_tokens=256,
      messages=[{"role": "user", "content": "Привет!"}],
  )
  ```
</CodeGroup>

## Что даёт ключ

Ключ даёт **полные права аккаунта** на базе `/api/v1`. У ключей нет:

* областей видимости — один ключ видит ровно то же, что видит аккаунт;
* списков разрешённых моделей — доступны все модели, доступные аккаунту;
* собственных лимитов запросов.

<Warning>
  Утечка ключа равносильна утечке доступа к аккаунту. С утёкшим ключом можно тратить ваш баланс, видеть ваши файлы в хранилище и вызывать любую доступную модель. Единственные ограничители — лимиты и тариф самого аккаунта, лимиты частоты запросов, IP-allow-list, если он настроен, и остаток кошелька.
</Warning>

Поэтому заводите по ключу на каждую интеграцию и на каждое окружение: прод, стенд, локальная разработка, отдельный пайплайн. Так при отзыве одного ключа вы не гасите остальные и точно знаете, куда идти разбираться.

## Эндпоинты без ключа

| Эндпоинт | Что возвращает без ключа |
| - | - |
| `GET /api/v1/models` | Каталог текстовых моделей с базовыми ценами |
| `GET /api/v1/media/models` | Каталог медиа-моделей, их схемы и цены |

Без ключа эти два эндпоинта отдают базовые цены; с ключом — цены вашего аккаунта. Остальным эндпоинтам ключ обязателен, при его отсутствии приходит `401 invalid_api_key`.

## Проверка ключа

Самый быстрый способ убедиться, что ключ рабочий — запрос баланса:

```bash cURL theme={null} theme={null}
curl https://speshu.ai/api/v1/balance \
  -H "Authorization: Bearer $SPESHU_API_KEY"
```

```json theme={null} theme={null}
{ "RUB": "1250.00", "USD": "3.75" }
```

Ответ с суммами означает, что ключ принят. Ответ `401` с `code: invalid_api_key` — ключ недействителен, отозван или истёк; разбираться нужно в разделе API-ключей в профиле.

## Ошибки аутентификации

| Код | `code` | Что означает |
| - | - | - |
| `401` | `invalid_api_key` | Ключ не передан, неизвестен, отозван или истёк |
| `401` | `unauthorized` | Запрос не прошёл проверку прав |

Полный разбор — на странице [Ошибки](/docs/errors).

## Безопасность ключа

* Храните ключ в переменной окружения или в менеджере секретов, а не в коде.
* Никогда не отправляйте ключ из клиентского кода браузера, мобильного приложения или десктопного клиента. Всё, что попало в клиент, попадёт к пользователю.
* Никогда не коммитьте ключ в репозиторий. Добавьте его в `.gitignore` заранее, до первой отправки.
* Ротируйте ключ так: создайте новый, переведите на него интеграцию, проверьте и только потом отзовите старый.
* Настройте IP-allow-list, если у вашей инфраструктуры есть стабильные адреса выхода. Это ограничивает круг источников, из которых ключ вообще работает.

## Что дальше

<CardGroup cols={2}>
  <Card title="Тарификация и оплата" icon="wallet" href="/docs/billing">
    Как считается стоимость и проверяется баланс
  </Card>

  <Card title="Модели и цены" icon="microchip" href="/docs/models">
    Каталог моделей и цены за миллион токенов
  </Card>

  <Card title="Баланс" icon="credit-card" href="/docs/api-reference/other/balance">
    Остаток кошелька по валютам
  </Card>

  <Card title="Ошибки" icon="triangle-exclamation" href="/docs/errors">
    Полная таблица кодов
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.