slen.ai
Начать

Как устроен API Slen

Базовый адрес, форма запроса и ответа и соглашения, которым следует каждая операция API.

4 мин чтения

API Slen — это HTTP API, который говорит на JSON. Все операции следуют одним и тем же немногим соглашениям. Эта страница называет их один раз, а страница каждого ресурса на них опирается.

Базовый адрес и версия

Все пути в этом справочнике заданы относительно одного базового адреса.

Base address
https://api.slen.ai/api

Пути API начинаются с /v1. Версия — часть пути, и этот справочник описывает версию 1. Две проверки состояния, /health и /ready, стоят вне /v1 и не требуют ключа.

Запрос

Запрос несёт API-ключ в заголовке Authorization — как именно, сказано в статье Аутентификация. Если операция принимает тело, это JSON, отправленный с заголовком Content-Type: application/json.

Terminal
curl https://api.slen.ai/api/v1/models \
  -H "Authorization: Bearer $SLEN_API_KEY"
200 OK
{
  "data": [
    {
      "model_code": "gpt-4o-mini",
      "provider": "openai",
      "model_price_id": "1108",
      "input_price_per_million": "0.15000000",
      "output_price_per_million": "0.60000000",
      "cached_input_price_per_million": "0.07500000",
      "max_output_tokens": 16384,
      "currency": "USD",
      "effective_from": "2026-01-01T00:00:00+00:00",
      "effective_to": null
    }
  ]
}

Запрос, который запускает флоу, и операции, которые двигают кредиты клиента, — пополнение, списание, корректировка — требуют ещё и заголовок Idempotency-Key. Это ваш собственный ключ, который называет одну единицу работы, поэтому у новой единицы работы — новый ключ. Страница ресурса помечает операции, которым он обязателен.

Успешный ответ

Успешный ответ — это JSON, в котором данные лежат внутри data: объект, когда вещь одна, и массив, когда это список.

Список, который читается постранично, добавляет meta. Возьмите meta.next_cursor из одной страницы и отправьте его параметром cursor следующего запроса. На последней странице он равен null.

Два вида ответов в data не обёрнуты:

  • у ответа со статусом 204 нет тела;

  • две проверки состояния отвечают простым объектом;

Ошибки

Запрос, который отклонён или завершился сбоем, отвечает статусом из семейства 4xx или 5xx. Ошибка, о которой сообщает сам API, приходит в одном конверте.

401 Unauthorized
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is missing or invalid",
    "request_id": "3f6c1a52-8f0e-4c1b-9a57-1d2e6b7c9f10"
  }
}
ПолеЧто в нём
error.codeПостоянное имя того, что произошло. Ветвите код по нему, а не по тексту.
error.messageОбъяснение для человека. Его формулировка может измениться.
error.detailsОбъект с подробностями — там, где код несёт структуру. В остальных случаях поля нет.
error.request_idИдентификатор запроса, тот же, что в заголовке ответа X-Request-Id.

Каждый код перечислен в статье Коды ошибок — с тем, что он значит и что с ним делать.

Ответ 422 бывает двух видов. Запрос, который отклонил сам продукт, отвечает конвертом выше. Поле, не прошедшее проверку, — пропущенное имя, число там, где ожидается строка, — отвечает полями message и errors: это соответствие имени поля списку того, что с ним не так.

Ещё несколько ответов тоже приходят без конверта: 404 для пути, которого у API нет, 405 для метода, который путь не принимает, 500 для сбоя, которого API не ожидал. В таком ответе есть message и нет error. Когда в ответе нет error, ветвите код по его статусу.

Как записываются значения

ЗначениеКак записывается
Имена полейsnake_case — и в запросе, и в ответе
ДеньгиДесятичная строка, никогда не число. В ответе восемь знаков после точки, например "0.02700000"
КредитыДесятичная строка с четырьмя знаками после точки, например "12.5000"
Доли и коэффициентыДесятичная строка, никогда не число, с тем числом знаков после точки, которое называет её поле, например "0.7500". Поле говорит и то, доля ли это от 1 или процент
ИдентификаторыСтрока из цифр, например "74438200973594624". Идентификатор слишком длинный для числа JavaScript
ВремяISO 8601 со смещением, например "2026-10-02T08:41:00+00:00"

Храните деньги и идентификаторы строками и на своей стороне. Значение, прочитанное в число с плавающей точкой, теряет знаки.

Идентификатор запроса

Каждый ответ несёт заголовок X-Request-Id — и при успехе, и при ошибке. Указывайте его, когда пишете в поддержку.

В том же заголовке можно прислать собственный идентификатор. Идентификатор длиной от 8 до 128 символов — буквы, цифры, ., _, : и - — сохраняется и возвращается. Любой другой заменяется новым.

Что читать дальше