Назад

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

Подробное описание API для интеграции с сервисом "Переводчик сленга"

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

Обзор API

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

Важно!

Все запросы к API требуют действительного API-ключа. API-ключи используются для:

  • Аутентификации запросов
  • Отслеживания использования API
  • Применения лимитов запросов

Получение API-ключа

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

Регистрация в сервисе

Для получения API-ключа необходимо иметь учетную запись в сервисе "Переводчик сленга". Если у вас ещё нет учетной записи, зарегистрируйтесь.

Создание API-ключа

После входа в систему перейдите в раздел "Настройки" → "API-ключи" и нажмите кнопку "Создать новый ключ". Введите название для вашего ключа и выберите необходимые уровни доступа.

Активация и использование

После создания ключа вы получите уникальный идентификатор, который необходимо включать в заголовок X-API-Key при выполнении запросов к API.

curl -X POST "https://api.slang-translator.ru/v1/translate" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: ваш_api_ключ" \
     -d '{"text": "Я вчера чилил дома"}'
Безопасность API-ключа

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

Интеграция API-ключа

После получения API-ключа вам необходимо интегрировать его в ваши запросы. Существует несколько способов передачи API-ключа при выполнении запросов к сервису:

1. В заголовке HTTP-запроса

Рекомендуемый способ — передача API-ключа в заголовке X-API-Key:

// JavaScript пример с использованием fetch
fetch('https://api.slang-translator.ru/v1/translate', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'ваш_api_ключ'
    },
    body: JSON.stringify({
        text: 'Это было очень кринжово'
    })
})
.then(response => response.json())
.then(data => console.log(data));

2. В параметрах запроса

Альтернативный способ — передача API-ключа как параметра запроса api_key:

GET https://api.slang-translator.ru/v1/dictionary?api_key=ваш_api_ключ

Примечание: Этот метод менее безопасен, так как API-ключ может сохраняться в журналах сервера и истории браузера.

3. В теле запроса (только для POST-запросов)

Для POST-запросов можно включить API-ключ в тело запроса:

{
    "api_key": "ваш_api_ключ",
    "text": "Мы вчера чилили с друзьями"
}

Основные конечные точки API

POST /v1/translate

Перевод текста, содержащего сленговые выражения

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

Параметр Тип Описание
text обязательный string Текст, содержащий сленговые выражения для перевода
format опциональный string Формат вывода результата: "html" или "plain" (по умолчанию: "plain")
include_examples опциональный boolean Включать ли примеры использования слов в ответе (по умолчанию: false)

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

curl -X POST "https://api.slang-translator.ru/v1/translate" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: ваш_api_ключ" \
     -d '{
        "text": "Вчера был на вписке, было очень душевно, но под конец все зафейлились.",
        "format": "html",
        "include_examples": true
     }'

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

{
    "original_text": "Вчера был на вписке, было очень душевно, но под конец все зафейлились.",
    "translated_text": "Вчера был на вписке (неформальная домашняя вечеринка), было очень душевно, но под конец все зафейлились (потерпели неудачу).",
    "found_slang": [
        {
            "word": "вписка",
            "meaning": "неформальная домашняя вечеринка",
            "example": "Пойдем в субботу на вписку к Антону?"
        },
        {
            "word": "зафейлились",
            "meaning": "потерпели неудачу",
            "example": "Мы зафейлились на этом этапе проекта."
        }
    ],
    "stats": {
        "slang_words_count": 2,
        "total_words_count": 12,
        "slang_percentage": 16.67
    }
}
GET /v1/dictionary

Получение списка сленговых слов

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

Параметр Тип Описание
query опциональный string Поисковый запрос для фильтрации сленговых слов
limit опциональный integer Количество слов в ответе (по умолчанию: 50, максимум: 100)
offset опциональный integer Смещение в списке слов для пагинации (по умолчанию: 0)

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

curl "https://api.slang-translator.ru/v1/dictionary?query=крип&limit=5" \
     -H "X-API-Key: ваш_api_ключ"

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

{
    "query": "крип",
    "total": 3,
    "items": [
        {
            "word": "крипово",
            "meaning": "жутко, страшно, тревожно",
            "example": "В этом заброшенном доме было очень крипово."
        },
        {
            "word": "криповый",
            "meaning": "странный, жуткий, пугающий",
            "example": "Этот тип такой криповый, я не хочу с ним общаться."
        },
        {
            "word": "крипер",
            "meaning": "странный человек, вызывающий дискомфорт",
            "example": "Не общайся с ним, он настоящий крипер."
        }
    ]
}

Лимиты и ограничения

API "Переводчика сленга" имеет ограничения на количество запросов для обеспечения стабильной работы сервиса. Лимиты зависят от типа вашего API-ключа:

Тип ключа Лимит запросов Другие ограничения
Бесплатный 100 запросов/день Максимум 1000 символов на запрос, без коммерческого использования
Базовый 1,000 запросов/день Максимум 5,000 символов на запрос
Премиум 10,000 запросов/день Максимум 10,000 символов на запрос, приоритетная обработка
Корпоративный Индивидуально Без ограничений по размеру текста, выделенная поддержка

При превышении лимита запросов API вернет ошибку 429 Too Many Requests. В заголовке ответа X-RateLimit-Remaining содержится информация о количестве оставшихся запросов в текущем периоде.

Обработка ошибок

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

Код Описание
200 OK Запрос выполнен успешно
400 Bad Request Неверные параметры запроса
401 Unauthorized Отсутствует или недействительный API-ключ
403 Forbidden Недостаточно прав для выполнения операции
429 Too Many Requests Превышен лимит запросов
500 Internal Server Error Внутренняя ошибка сервера

Пример ответа с ошибкой

{
    "error": {
        "code": 401,
        "message": "Недействительный API-ключ. Проверьте правильность ключа или получите новый в личном кабинете.",
        "request_id": "f8c3de3d-1cb3-4a6a-9a0f-25e9c1b3abcd"
    }
}

При обращении в службу поддержки всегда указывайте request_id из ответа с ошибкой, это поможет быстрее идентифицировать и решить проблему.

Примеры интеграции

Пример на JavaScript

// Функция для перевода текста с помощью API
async function translateSlang(text, apiKey) {
    try {
        const response = await fetch('https://api.slang-translator.ru/v1/translate', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': apiKey
            },
            body: JSON.stringify({
                text: text,
                format: 'html'
            })
        });
        
        if (!response.ok) {
            const errorData = await response.json();
            throw new Error(`API Error: ${errorData.error.message}`);
        }
        
        return await response.json();
    } catch (error) {
        console.error('Translation failed:', error);
        throw error;
    }
}

// Пример использования
document.getElementById('translate-btn').addEventListener('click', async () => {
    const text = document.getElementById('input-text').value;
    const apiKey = 'ваш_api_ключ';
    
    try {
        const result = await translateSlang(text, apiKey);
        document.getElementById('result').innerHTML = result.translated_text;
    } catch (error) {
        document.getElementById('result').innerHTML = `

${error.message}

`; } });

Пример на Python

import requests

def translate_slang(text, api_key):
    """
    Translate text containing slang words using the API
    """
    url = "https://api.slang-translator.ru/v1/translate"
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": api_key
    }
    payload = {
        "text": text,
        "format": "plain",
        "include_examples": True
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()  # Raise exception for 4XX/5XX responses
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error during API request: {e}")
        if hasattr(e, 'response') and e.response:
            print(f"API error: {e.response.text}")
        return None

# Example usage
if __name__ == "__main__":
    api_key = "ваш_api_ключ"
    text = "Этот концерт был просто вау! Мы чилили всю ночь."
    
    result = translate_slang(text, api_key)
    if result:
        print("Original text:", result["original_text"])
        print("Translated text:", result["translated_text"])
        print("\nFound slang words:")
        for slang in result["found_slang"]:
            print(f"- {slang['word']}: {slang['meaning']}")
            print(f"  Example: {slang['example']}")