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 символів — літери, цифри, ., _, : і - — зберігається й повертається. Будь-який інший замінюється новим.

Що читати далі