API

Документация API

REST-API для модерации текста: один запрос возвращает категории вреда, оценку рекламы и итоговый вердикт.

Быстрый старт #

Выпустите ключ в панели — он начинается с sk_live_.
Передайте ключ в заголовке x-api-key.
Отправьте текст в POST /v1/moderate и прочитайте вердикт из JSON.

curl https://sculkward.com/v1/moderate \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"input": "продам акк дёшево, пиши в тг @seller"}'

const res = await fetch("https://sculkward.com/v1/moderate", {
  method: "POST",
  headers: {
    "x-api-key": "sk_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "продам акк дёшево, пиши в тг @seller",
  }),
});
const verdict = await res.json();
console.log(verdict.flagged);

import requests

res = requests.post(
    "https://sculkward.com/v1/moderate",
    headers={"x-api-key": "sk_live_xxx"},
    json={"input": "продам акк дёшево, пиши в тг @seller"},
)
verdict = res.json()
print(verdict["flagged"])

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

Каждый запрос к /v1 требует ключ вида sk_live_…. Передайте его одним из двух способов:

x-api-key: sk_live_xxx

Authorization: Bearer sk_live_xxx

Держите ключ на сервере. Не публикуйте его в браузерном коде или репозитории. Отсутствующий или неверный ключ даёт 401; скомпрометированный ключ отзывается в панели.

Эндпоинты #

Метод	Путь	Назначение
POST	`/v1/moderate`	Проверить текст и получить вердикт.
GET	`/v1/moderate/{id}`	Забрать отложенный результат по `id`.
GET	`/v1/usage`	Сводка использования по ключу.
GET	`/v1/health`	Статус сервиса (без ключа).

POST `/v1/moderate` #

Проверяет текст и возвращает вердикт: категории вреда, их оценки и блок рекламы.

Параметры

Поле	Тип	Описание
`input` обязательное	string	Текст для проверки. Пустой даёт `400`.
`image_url` beta	string	Ссылка на изображение. Модерация изображений в разработке — поле пока не обрабатывается.

Ответ 200 OK #

Поле	Тип	Описание
`id`	string	Идентификатор вердикта (`mod_…`).
`flagged`	bool	Итоговый флаг: сработала хотя бы одна категория или реклама.
`categories`	object	Булев флаг по каждой категории — порог уже применён.
`category_scores`	object · 0…1	Числовая оценка каждой категории — для собственных порогов.
`ad`	object	Оценка рекламы: `is_ad`, `score`, `kind`, `reasons`. См. Поле ad.
`cached`	bool	true, если ответ отдан из кэша; повтор того же текста не тратит квоту.
`engine`	string	Версия движка (`sculk-v1`).

{
  "id": "mod_3f9a2b7c8d1e4f50a6b3c2d1e0f9a8b7",
  "flagged": true,
  "categories": {
    "harassment": false,
    "hate": false,
    "sexual": false,
    "violence": false,
    "self_harm": false,
    "illicit": false
  },
  "category_scores": {
    "harassment": 0.05,
    "hate": 0.02,
    "sexual": 0.01,
    "violence": 0.03,
    "self_harm": 0.00,
    "illicit": 0.04
  },
  "ad": {
    "is_ad": true,
    "score": 0.92,
    "kind": "contact",
    "reasons": ["handle", "promo_lexicon"]
  },
  "cached": false,
  "engine": "sculk-v1"
}

Обычно вердикт приходит сразу. На тарифах post запрос ставится в очередь: ответ — 202 с id, а готовый вердикт забирается через GET /v1/moderate/{id}.

Категории #

У части категорий есть уточняющие под-категории — например harassment_threatening.

harassment

Травля и оскорбления в адрес человека.

hate

Ненависть и дискриминация по признаку.

sexual

Сексуальный контент.

violence

Насилие и угрозы.

self_harm

Самоповреждение и суицид.

illicit

Противоправные действия и инструкции.

Поле `ad` #

Оценка рекламы и спама.

Поле	Тип	Значение
`is_ad`	bool	Реклама/спам обнаружены (порог применён).
`score`	number · 0…1	Оценка уверенности.
`kind`	string	`promo` · `spam` · `contact` · `link` · `none`.
`reasons`	array	Сработавшие сигналы: `link`, `handle`, `contact`, `promo_lexicon`, `crypto`.

GET `/v1/usage` #

Сводка по ключу: всего запросов, сколько отдано из кэша, текущий тариф.

{
  "total": 18432,
  "cached": 5120,
  "tier": "pro"
}

Ошибки #

Ошибки приходят единым конвертом с машиночитаемым type и текстом message:

{
  "error": {
    "type": "validation",
    "message": "input must not be empty"
  }
}

HTTP	type	Когда
`400`	`validation`	Пустой `input` или некорректное тело.
`401`	`unauthorized`	Нет ключа или ключ неверный/отозван.
`402`	`payment_required`	Недостаточно баланса для платного запроса.
`404`	`not_found`	Неизвестный `id` отложенной задачи.
`429`	`rate_limited`	Превышена дневная квота тарифа.
`500`	`internal`	Внутренняя ошибка сервиса.

Режим обработки и дневная квота задаются тарифом ключа; лимиты считаются по UTC-суткам. Смотреть тарифы →