API

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

Подключите SculkWard, отправьте сообщение и получите решение для автоматического действия или ручной проверки.

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

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

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

const res = await fetch("https://sculkward.com/v1/moderate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer 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={
        "Authorization": "Bearer sk_live_xxx",
        "Content-Type": "application/json",
    },
    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`	Проверить текст и получить готовый вердикт.
POST	`/v1/moderate/batch`	Проверить до 32 текстов синхронно одним запросом.
GET	`/v1/usage`	Сводка использования по ключу.
GET	`/v1/health`	Статус сервиса (без ключа).

POST`/v1/moderate`#

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

Параметры

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

POST`/v1/moderate/batch`#

Синхронно проверяет от 1 до 32 элементов и возвращает массив results в исходном порядке. Каждый элемент завершается независимо: ошибка одного не скрывает успешные соседние результаты.

curl https://sculkward.com/v1/moderate/batch \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"custom_id":"msg-1","input":"first message"},{"custom_id":"msg-2","input":"second message"}]}'

const res = await fetch("https://sculkward.com/v1/moderate/batch", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      { custom_id: "msg-1", input: "first message" },
      { custom_id: "msg-2", input: "second message" },
    ],
  }),
});
const batch = await res.json();

Лимиты: 32 KiB на элемент, 512 KiB на JSON-тело и до 64 символов в custom_id. custom_id должны быть уникальны внутри одного пакета.

Результаты сохраняют порядок input. Переданный custom_id возвращается в ответе и позволяет надёжно сопоставить элементы.

Верхнеуровневый request_id обозначает попытку HTTP-запроса. Каждый успешный result содержит свой id конкретного результата модерации.

Структурно неверный пакет даёт HTTP 400. После приёма эндпоинт возвращает HTTP 200 с поэлементным status: ok или error. Повторяйте overloaded и upstream ошибки с экспоненциальной задержкой и случайным разбросом.

Ответ200 OK#

Поле	Тип	Описание
`id`	string	Идентификатор результата, возвращённый в этом ответе с вердиктом.
`request_id`	string	Идентификатор конкретной попытки запроса для трассировки и поддержки.
`flagged`	bool	Итоговый флаг: сработала хотя бы одна категория или реклама.
`categories`	object	Булев флаг по каждой категории — порог уже применён.
`category_scores`	object · 0…1	Числовая оценка каждой категории — для собственных порогов.
`ad`	object	Числовая оценка вероятности рекламы.

{
  "id": "mod_3f9a2b7c8d1e4f50a6b3c2d1e0f9a8b7",
  "request_id": "req_123456781234423482341234567890ab",
  "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": {
    "score": 0.92
  }
}

Сохраняйте оба идентификатора: id обозначает результат, возвращённый в этом ответе с вердиктом, а request_id — конкретную попытку запроса для трассировки и поддержки.

Категории#

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

harassment

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

hate

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

sexual

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

violence

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

self_harm

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

illicit

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

Реклама`ad`#

Оценка нежелательной рекламы.

Поле	Тип	Значение
`score`	number · 0…1	Оценка вероятности рекламы от 0 до 1.

GET`/v1/usage`#

Общее количество запросов, выполненных с этим ключом.

{
  "total": 18432
}

Ошибки#

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

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

HTTP	Тип	Когда
400	`validation`	Пустой input или некорректное тело.
401	`unauthorized`	Нет ключа или ключ неверный либо отозван.
402	`payment_required`	Недостаточно баланса для платного запроса.
404	`not_found`	Запрошенный ресурс не найден.
429	`rate_limited`	Превышена дневная квота тарифа.
503	`overloaded`	Мощность модерации временно исчерпана. Повторите запрос с экспоненциальной задержкой и случайным разбросом; это не сбой внешней зависимости.
503	`upstream`	Проверка временно недоступна — повторите запрос позже.
500	`internal`	Внутренняя ошибка сервиса.

Дневной лимит зависит от тарифа и обновляется в начале UTC-суток. Смотреть тарифы