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

Каждый вызов API, который создаёт или читает данные либо связан с оплатой, должен передавать ваш API-ключ в заголовке Authorization. Единственное исключение — публичный каталог моделей для ознакомления: ключ для него не нужен.

Authorization: Bearer sk-spicy-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Нативный API (/api/v1/*) принимает только Bearer-ключи — без cookies и параметров в строке запроса.

Эндпоинты совместимости для текста и видео (/v1, /v1beta) используют тот же ключ и также принимают заголовок x-api-key, используемый SDK Anthropic, и заголовок x-goog-api-key, используемый SDK Google GenAI. Поэтому в официальных SDK достаточно изменить базовый URL — см. Текст и потоковые ответы. Эти два заголовка не действуют на /api/v1, и ни один эндпоинт не принимает ключ в параметрах URL.

API-ключи и консоль используют разную авторизацию

API-ключи принимают только /api/v1, /v1 и /v1beta. Веб-консоль использует отдельную браузерную сессию. Поэтому сессия входа в консоль не может служить API-ключом, а утёкший API-ключ не позволяет войти в консоль. Передача неподходящего типа учётных данных всегда возвращает 401, а не ошибку прав доступа.

Как выглядит ключ

Фиксированный префикс sk-spicy-, за которым идут 48 строчных шестнадцатеричных символов.

Префикс выбран намеренно: лучше получить уведомление сканера, чем узнать об утечке после того, как кто-то потратил ваш баланс.

Как создать ключ

1. Откройте Консоль → API-ключи и нажмите Создать ключ.
2. Назовите его по сервису, который будет его использовать (production backend, staging worker). При отзыве ключа вам потребуется узнать его среди остальных.
3. При необходимости откройте Дополнительно, чтобы задать лимиты расходов, список разрешённых моделей, список разрешённых IP-адресов и срок действия. Все эти настройки можно изменить позже.
4. Скопируйте ключ или нажмите Сохранить в файл и подтвердите, что сохранили его. После закрытия диалога показать ключ снова нельзя.

Создавать ключи могут владелец, администратор или разработчик команды. Ключ принадлежит команде, выбранной в левом верхнем углу консоли: его расходы и лимиты учитываются в рамках этой команды. В каждой команде может быть до 50 активных ключей. Для платных операций аккаунту также нужны подтверждённый адрес электронной почты и баланс; см. Настройка аккаунта.

Где хранить ключ

• На своём компьютере для тестирования: задайте export SPICY_API_KEY="…" в терминале (переменная действует до закрытия окна) или используйте файл .env, который загружает ваш код. Добавьте .env в .gitignore до первого коммита.
• На сервере или платформе хостинга: используйте настройки секретов или переменных окружения и читайте SPICY_API_KEY из окружения в коде.
• Никогда не вставляйте ключ в исходный код, чат, скриншот, обращение в поддержку или промпт для AI-ассистента.

Не передавайте ключ клиенту

То же касается мобильных приложений, настольных клиентов, публичных ноутбуков, логов CI и любых данных, которые попадут в вывод curl -v, скопированный в обращение в поддержку.

Ваши собственные инструменты в вашем собственном браузере — другой случай. API принимает браузерные вызовы, поэтому инструменты для личного использования, например расширение SillyTavern или приложение для ролевых диалогов, куда вы вставляете собственный ключ, могут обращаться к нему напрямую. Правило выше относится к встраиванию ключа в то, что загружают другие люди. Выдавайте каждому такому инструменту отдельный ключ с дневным лимитом: так вы сможете видеть его расходы и отозвать его независимо от остальных.

Ограничения отдельного ключа

Настройте их в консоли при создании ключа или позже. Ограничения применяются на стороне сервера.

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

В лимитах учитываются и средства, зарезервированные под выполняющиеся задачи, и уже потраченные деньги. Поэтому ключ может достичь лимита, пока задачи ещё выполняются. Поле msg указывает, какой именно лимит достигнут. Если при 40202 поле msg упоминает квоту платформы, дело не в вашем ключе: создание другого ключа не поможет, повторите запрос позже.

Список разрешённых IP-адресов проверяется по вашему фактическому публичному адресу, который видит наша пограничная сеть, а не по адресу последнего прокси. Исходящий адрес — публичный IP, с которого отправляются запросы вашего сервера. Большинство хостингов указывает его в сетевых настройках; на своём компьютере его можно посмотреть командой curl https://ifconfig.me.

Задачи принадлежат создавшему их ключу

Через API задача видна только тому API-ключу, который её создал. При использовании любого другого ключа, даже из той же команды:

Два механизма не привязаны к ключу. Вебхуки задачи доставляются даже после отзыва создавшего её ключа. Кроме того, все задачи команды, независимо от ключа, доступны в разделе Консоль → Логи, а в деталях каждой задачи указан Использованный ключ.

Замена ключей

• Отдельный ключ для каждой среды (рабочая / тестовая / локальная), чтобы можно было отозвать один, не затрагивая остальные.
• Плановая замена: создайте новый ключ и отправляйте с ним только новые задачи. Оставьте старый ключ активным, пока все созданные им задачи не достигнут конечного состояния (не позже соответствующего deadlineAt) и вы не получите результаты, затем отзовите его. Используйте такой порядок только если старый ключ всё ещё надёжен.
• Отзыв действует сразу и необратим. Не нужно ждать истечения кеша; повторно включить ключ нельзя — требуется создать новый.

Если ключ утёк

Если возникли неожиданные расходы, обратитесь через Консоль → Поддержка и передайте ID задач или значения request_id.

Как выглядит ошибка

{
  "code": 401,
  "msg": "Credentials are invalid or expired",
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

HTTP-статус также будет 401. Любая ошибка аутентификации возвращает code: 401, а msg указывает её тип:

Обрабатывайте code, а не текст: формулировка может меняться и зависит от языка ошибок. Подробнее о различиях — в разделе Ошибки.

Если сам аккаунт не может вызывать API (электронная почта не подтверждена или аккаунт приостановлен), вы получите 403. Замена ключа в этом случае не поможет.