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

Обзор

ruSpam API предоставляет доступ к нашей системе классификации спама через простые HTTP-запросы. API позволяет интегрировать функциональность обнаружения спама в ваши приложения и сервисы.

Все запросы к API требуют аутентификации с использованием токена API, который должен быть передан в заголовке запроса.

Базовый URL

https://ru-spam.ru

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

Все запросы к API должны включать токен в заголовке token.

token: ваш_api_токен

Получение API токена

Для использования API вам необходим персональный токен доступа. Получить токен можно через Telegram бота:

@AntiSpam_moder_bot

Отправьте команду /apikey боту, чтобы получить персональный токен.

Пошаговая инструкция

  1. Откройте Telegram и найдите бота @AntiSpam_moder_bot
  2. Нажмите кнопку "Старт" или отправьте команду /start
  3. Отправьте команду /apikey
  4. Бот выдаст вам персональный токен и инструкции по его использованию
  5. Скопируйте полученный токен и используйте его в заголовке ваших API запросов

Эндпоинты API

POST

/classify

Классифицирует текст как спам или не спам с использованием нейросетевой модели.

Стоимость: 0,05 руб за запрос

Лимит: 20 запросов в минуту на токен

При превышении возвращается 429 Too Many Requests.

Параметры запроса

Параметр Тип Описание
text string Текст для классификации

Пример запроса

{
  "text": "Привет! Как дела? Хочу предложить тебе выгодную инвестицию с доходностью 500% в месяц!"
}

Пример на Python

import requests
import json

# Настройки API
API_URL = "https://ru-spam.ru/classify"
API_TOKEN = "ваш_api_токен"

# Заголовки запроса
headers = {
    "Content-Type": "application/json",
    "token": API_TOKEN
}

# Данные для классификации
data = {
    "text": "Привет! Как дела? Хочу предложить тебе выгодную инвестицию с доходностью 500% в месяц!"
}

try:
    # Отправка запроса
    response = requests.post(API_URL, headers=headers, json=data)
    
    # Проверка статуса ответа
    if response.status_code == 200:
        result = response.json()
        
        print(f"Результат классификации:")
        print(f"Спам: {'Да' if result['is_spam'] else 'Нет'}")
        print(f"Уверенность: {result['confidence']:.2%}")
        print(f"Время обработки: {result['processing_time']:.3f} сек")
        print(f"Стоимость: {result['cost']} руб")
        print(f"Остаток на балансе: {result['remaining_balance']} руб")
    else:
        print(f"Ошибка: {response.status_code}")
        print(response.text)

except requests.exceptions.RequestException as e:
    print(f"Ошибка запроса: {e}")

Пример ответа

{
  "processing_time": 0.023,
  "cost": 0.05,
  "remaining_balance": 9.95,
  "is_spam": true,
  "confidence": 0.98,
  "rate_limit": {
    "limit": 20,
    "remaining": 19,
    "reset_in_seconds": 42
  }
}

Пример ответа при превышении лимита (429)

{
  "detail": {
    "message": "Rate limit exceeded",
    "limit": 20,
    "remaining": 0,
    "reset_in_seconds": 37,
    "endpoint": "classify"
  }
}
POST

/classify_advanced

Новое

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

Стоимость: 0,1 руб за запрос

Лимит: 10 запросов в минуту на токен

При превышении возвращается 429 Too Many Requests.

Параметры запроса

Параметр Тип Обязательный Описание
text string Да Текст для классификации
avatar_base64 string Нет Аватарка пользователя в формате base64
bio string Нет Биография пользователя
has_premium boolean Нет Наличие Telegram Premium
group_name string Нет Название группы
group_description string Нет Описание группы
reply_to_message object Нет Информация о сообщении, на которое отвечают

Пример запроса

{
  "text": "Привет! Хочу предложить тебе выгодную инвестицию!",
  "bio": "Инвестиционный консультант 💰 Помогу заработать!",
  "has_premium": false,
  "group_name": "Криптоинвестиции",
  "group_description": "Обсуждение криптовалют и инвестиций"
}

Пример на Python

import requests
import json
import base64

# Настройки API
API_URL = "https://ru-spam.ru/classify_advanced"
API_TOKEN = "ваш_api_токен"

# Заголовки запроса
headers = {
    "Content-Type": "application/json",
    "token": API_TOKEN
}

# Функция для кодирования изображения в base64
def encode_image_to_base64(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

# Данные для продвинутой классификации
data = {
    "text": "Привет! Хочу предложить тебе выгодную инвестицию!",
    "bio": "Инвестиционный консультант 💰 Помогу заработать!",
    "has_premium": False,
    "group_name": "Криптоинвестиции",
    "group_description": "Обсуждение криптовалют и инвестиций",
    # "avatar_base64": encode_image_to_base64("avatar.jpg")  # Опционально
}

response = requests.post(API_URL, headers=headers, json=data)
result = response.json()

Пример ответа

{
  "processing_time": 1.247,
  "cost": 0.1,
  "remaining_balance": 9.9,
  "is_spam": true,
  "category": 1,
  "category_name": "SPAM",
  "should_delete": true,
  "model_used": "darkguard_model",
  "rate_limit": {
    "limit": 2,
    "remaining": 1,
    "reset_in_seconds": 53
  },
  "categories": {
    "0": "NORMAL - Regular messages",
    "1": "SPAM - Fraud, unwanted ads", 
    "2": "ADULT - 18+ content",
    "4": "COMMERCE - Commercial ads"
  }
}

Пример ответа при превышении лимита (429)

{
  "detail": {
    "message": "Rate limit exceeded",
    "limit": 2,
    "remaining": 0,
    "reset_in_seconds": 45,
    "endpoint": "classify_advanced"
  }
}

Категории классификации

0 - NORMAL

Обычные сообщения, не содержащие спама

1 - SPAM

Спам-сообщения, мошенничество, нежелательная реклама

2 - ADULT

Контент для взрослых, 18+ материалы

4 - COMMERCE

Легальная коммерческая деятельность, реклама

GET

/api_stats

Возвращает статистику использования API для указанного токена за последние N дней.

Параметры запроса

Параметр Тип Описание
days integer Количество дней для статистики (по умолчанию 30)

Пример на Python

import requests

# Настройки API
API_URL = "https://ru-spam.ru/api_stats"
API_TOKEN = "ваш_api_токен"

# Заголовки запроса
headers = {
    "token": API_TOKEN
}

# Параметры запроса (опционально)
params = {
    "days": 30  # статистика за последние 30 дней
}

try:
    # Отправка GET запроса
    response = requests.get(API_URL, headers=headers, params=params)
    
    # Проверка статуса ответа
    if response.status_code == 200:
        stats = response.json()
        
        print(f"Статистика API за {stats['days']} дней:")
        print(f"Текущий баланс: {stats['current_balance']} руб")
        print(f"")
        print(f"Общая статистика:")
        print(f"- Всего запросов: {stats['summary']['total_requests']}")
        print(f"- Потрачено токенов: {stats['summary']['total_tokens']}")
        print(f"- Найдено спама: {stats['summary']['total_spam']}")
        print(f"- Не спам: {stats['summary']['total_non_spam']}")
        print(f"- Общая стоимость: {stats['summary']['total_cost']} руб")
        
        print(f"")
        print(f"Последние дни:")
        for day_stat in stats['daily_stats'][-5:]:  # Показать последние 5 дней
            print(f"- {day_stat['date']}: {day_stat['requests_count']} запросов, {day_stat['total_cost']} руб")
    else:
        print(f"Ошибка: {response.status_code}")
        print(response.text)

except requests.exceptions.RequestException as e:
    print(f"Ошибка запроса: {e}")

Пример ответа

{
  "token": "ваш_api_токен",
  "current_balance": 9.83,
  "days": 30,
  "daily_stats": [
    {
      "date": "2023-07-01",
      "requests_count": 120,
      "total_tokens": 1500,
      "spam_count": 45,
      "non_spam_count": 75,
      "total_cost": 0.9
    },
    // ...другие дни
  ],
  "summary": {
    "total_requests": 3500,
    "total_tokens": 42000,
    "total_spam": 1200,
    "total_non_spam": 2300,
    "total_cost": 25.2
  }
}

Коды ошибок

Код Описание
401 Отсутствует или неверный токен API
403 Недостаточно средств на балансе
429 Превышен лимит запросов (Too Many Requests). Тело содержит подробности: limit, remaining, reset_in_seconds, endpoint.
500 Внутренняя ошибка сервера