Описание API

Техническая документация API Zhivly. Интеграция сервиса в ваши приложения, примеры кода и описание эндпоинтов.

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

Zhivly предоставляет REST API для интеграции сервиса в ваши приложения. API доступен для пользователей Pro-тарифа.

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

Для использования API вам понадобится API ключ, который можно найти в личном кабинете в разделе "Настройки".

Авторизация

Authorization: Bearer ваш-api-ключ

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

Базовый URL

https://api.zhivly.ru/v1

Эндпоинты

Преобразование текста

POST /transform

Преобразует текст в более естественный с указанной тональностью.

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

ПараметрТипОбязательныйОписание
textstringДаТекст для преобразования (макс. 5000 символов)
tonestringДаТональность: neutral, friendly, formal, professional, casual
providerstringНетПровайдер ИИ (определяется автоматически)

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

curl -X POST "https://api.zhivly.ru/v1/transform" \
  -H "Authorization: Bearer ваш-api-ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "В рамках осуществления деятельности компания стремится к оптимизации бизнес-процессов.",
    "tone": "neutral"
  }'

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

{
  "success": true,
  "data": {
    "result": "Компания стремится оптимизировать бизнес-процессы в своей деятельности.",
    "provider": "ai",
    "model": "neural-network",
    "tokensUsed": {
      "input": 25,
      "output": 18
    }
  }
}

Возможные ошибки

Код статусаОшибкаОписание
400Bad RequestНеверный формат запроса
401UnauthorizedНеверный API ключ
402Payment RequiredТребуется Pro-подписка
413Payload Too LargeТекст превышает 5000 символов
429Too Many RequestsПревышен лимит запросов
500Internal Server ErrorВнутренняя ошибка сервера

Получение информации о пользователе

GET /user

Возвращает информацию о текущем пользователе и его подписке.

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

{
  "id": "user_123",
  "email": "[email protected]",
  "name": "Иван Иванов",
  "plan": "pro",
  "subscription": {
    "status": "active",
    "expires_at": "2024-12-31T23:59:59Z",
    "characters_limit": null,
    "characters_used": 15420
  },
  "api_usage": {
    "requests_this_month": 142,
    "characters_this_month": 45320
  }
}

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

GET /stats

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

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

ПараметрТипОбязательныйОписание
periodstringНетПериод: day, week, month, year (по умолчанию: month)
fromdateНетНачальная дата (YYYY-MM-DD)
todateНетКонечная дата (YYYY-MM-DD)

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

{
  "period": "month",
  "from": "2024-01-01",
  "to": "2024-01-31",
  "stats": {
    "total_requests": 142,
    "total_characters": 45320,
    "average_request_size": 319,
    "tone_usage": {
      "neutral": 45,
      "friendly": 38,
      "formal": 32,
      "professional": 20,
      "casual": 7
    },
    "daily_usage": [
      {
        "date": "2024-01-01",
        "requests": 12,
        "characters": 3840
      },
      {
        "date": "2024-01-02",
        "requests": 8,
        "characters": 2560
      }
    ]
  }
}

Лимиты и квоты

Ограничения

  • Максимальный размер текста: 5000 символов
  • Максимальное количество запросов: 100 в минуту
  • Максимальное количество запросов: 10 000 в месяц

Сбор статистики

Мы собираем следующую информацию:

  • Количество запросов
  • Объём обработанных символов
  • Используемые тональности
  • Время обработки запросов

Данные пользователей и тексты не сохраняются.

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

Python

import requests
import json
 
# Конфигурация
API_KEY = "ваш-api-ключ"
API_URL = "https://api.zhivly.ru/v1"
 
# Преобразование текста
def transform_text(text, tone="neutral"):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
 
    data = {
        "text": text,
        "tone": tone
    }
 
    response = requests.post(
        f"{API_URL}/transform",
        headers=headers,
        json=data
    )
 
    if response.status_code == 200:
        result = response.json()
        return result["data"]["result"]
    else:
        raise Exception(f"Error {response.status_code}: {response.text}")
 
# Использование
original_text = "В рамках осуществления деятельности..."
transformed_text = transform_text(original_text, "friendly")
print(transformed_text)

JavaScript

// Преобразование текста
async function transformText(text, tone = 'neutral') {
  const response = await fetch('https://api.zhivly.ru/v1/transform', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text: text,
      tone: tone,
    }),
  })
 
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`)
  }
 
  const data = await response.json()
  return data.data.result
}
 
// Использование
const originalText = 'В рамках осуществления деятельности...'
const transformedText = await transformText(originalText, 'friendly')
console.log(transformedText)

PHP

<?php
$apiKey = 'ваш-api-ключ';
$apiUrl = 'https://api.zhivly.ru/v1';
 
function transformText($text, $tone = 'neutral') {
    global $apiKey, $apiUrl;
 
    $data = [
        'text' => $text,
        'tone' => $tone
    ];
 
    $ch = curl_init($apiUrl . '/transform');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
 
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
 
    if ($httpCode !== 200) {
        throw new Exception("API request failed with code $httpCode");
    }
 
    $result = json_decode($response, true);
    return $result['data']['result'];
}
 
// Использование
$originalText = "В рамках осуществления деятельности...";
$transformedText = transformText($originalText, 'friendly');
echo $transformedText;
?>

Вебхуки

Zhivly поддерживает вебхуки для уведомлений о событиях.

Настройка вебхуков

Добавьте URL вебхука в личном кабинете в разделе "Интеграции".

События

transform.completed

Отправляется после каждого успешного преобразования текста.

{
  "event": "transform.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "request_id": "req_123",
    "characters_in": 156,
    "characters_out": 142,
    "tone": "friendly",
    "processing_time": 2.5
  }
}

subscription.expired

Отправляется при истечении подписки.

{
  "event": "subscription.expired",
  "timestamp": "2024-01-31T23:59:59Z",
  "data": {
    "user_id": "user_123",
    "plan": "pro",
    "expired_at": "2024-01-31T23:59:59Z"
  }
}

SDK

Мы предоставляем официальные SDK для популярных языков:

Python SDK

pip install zhivly

Node.js SDK

npm install zhivly

Подробная документация по SDK доступна в соответствующих репозиториях.

Тестирование

Перед использованием в production вы можете тестировать API в песочнице. Для этого используйте специальный тестовый API ключ.

Тестовый эндпоинт

POST /test/transform

Этот эндпоинт работает как обычный /transform, но не тратит ваши лимиты и всегда возвращает предопределённые ответы.

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

Рекомендации

  1. Всегда проверяйте HTTP статус код ответа
  2. Реализуйте повторные запросы при ошибках 5xx
  3. Соблюдайте лимиты запросов
  4. Обрабатывайте различные типы ошибок

Пример обработки ошибок (Python)

import time
import requests
 
def transform_text_with_retry(text, tone, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(/* параметры запроса */)
 
            if response.status_code == 200:
                return response.json()['data']['result']
            elif response.status_code == 429:
                # Too many requests - ждем
                retry_after = int(response.headers.get('Retry-After', 1))
                time.sleep(retry_after)
                continue
            elif response.status_code >= 500:
                # Server error - пробуем ещё раз
                if attempt < max_retries - 1:
                    time.sleep(2 ** attempt)
                    continue
 
            # Другие ошибки
            response.raise_for_status()
 
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
 
    raise Exception("Max retries exceeded")

Безопасность

Рекомендации

  1. Храните API ключ в безопасности
  2. Используйте HTTPS для всех запросов
  3. Не передавайте API ключ в URL
  4. Регулярно обновляйте ключ
  5. Используйте переменные окружения для хранения ключа

Пример безопасного хранения ключа

# .env файл
ZHIVLY_API_KEY=ваш-секретный-ключ
# Python
import os
from dotenv import load_dotenv
 
load_dotenv()
api_key = os.getenv('ZHIVLY_API_KEY')

Поддержка

Если у вас возникли вопросы по использованию API:

  1. Проверьте эту документацию
  2. Посмотрите FAQ
  3. Напишите на [email protected]

Для Pro-пользователей доступна приоритетная техническая поддержка.

Версия API: v1
Последнее обновление: Январь 2024