markclean-doc/api.md

# 📖 MarkClean API — Документация по использованию API-ключа

> **Версия API:** `v1`  
> **Базовый URL:** `https://markclean.online/api`  
> **Формат данных:** JSON  
> **Аутентификация:** API-ключ (`X-API-Key` / `Authorization: Bearer`) для `/convert` и `/converter/history`; HTTP-сессия (cookie `session_id`) для учётной, API-key и биллинга

---

## 📑 Содержание

1. [Обзор](#-обзор)
2. [Получение API-ключа](#-получение-api-ключа)
3. [Аутентификация](#-аутентификация)
4. [Конвертация URL в Markdown](#-конвертация-url-в-markdown)
5. [История конвертаций](#-история-конвертаций)
6. [Опции конвертации](#-опции-конвертации)
7. [API-ключи](#-api-ключи)
8. [Биллинг: пакеты и подписки](#-биллингпакеты-и-подписки)
9. [Проверка баланса](#-проверка-баланса)
10. [Обработка ошибок](#-обработка-ошибок)
11. [Квоты, лимиты и кэширование](#-квотылимиты-и-кэширование)
12. [Примеры кода](#-примеры-кода)
13. [FAQ](#-faq)

---

## 🔍 Обзор

MarkClean API позволяет программно конвертировать веб-страницы в чистый Markdown, оптимизированный для LLM, RAG-систем и документации.

**Ключевые возможности:**
- 🌐 Конвертация любой HTML-страницы в Markdown
- 🧹 Автоматическая очистка от мусора (реклама, навигация, футеры) через Readability
- ⚡ Двухуровневое кэширование — повторные запросы не списывают кредиты
- 🎛️ Гибкие опции вывода (заголовок, frontmatter, оглавление, удаление картинок/ссылок)
- 📊 История всех конвертаций с дедупликацией
- 💳 Система кредитов + ежедневный лимит + подписка
- 🗝️ Управление API-ключами (создание, чтение, удаление)
- 📦 Пакеты кредитов и подписки

---

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

API-ключ можно создать **только** через веб-интерфейс (требует авторизации по сессии).

### Шаги:

1. Войдите в аккаунт на [markclean.online](https://markclean.online)
2. Перейдите на страницу **API Keys** (или откройте `/api-keys`)
3. Нажмите **"Сгенерировать ключ"**
4. **⚠️ ВАЖНО:** Сохраните ключ немедленно — он будет показан **только один раз!**

### Формат ключа

```
mk_live_Xk9mP2vQ7rT4wL8nZ3sY6tB1cD5fG0hJ
│       └── 32 символа base64url (криптографически случайные, 24 байта)
└── префикс (8 символов)
```

**Общая длина:** 40 символов

> 🔒 **Безопасность:** В базе данных хранится только SHA-256 хеш ключа. Если вы потеряете ключ — восстановить его невозможно, только создать новый.

---

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

API поддерживает два независимых способа авторизации:

### 1. API-ключ (для API-клиентов)

Все запросы к защищённым эндпоинтам должны содержать API-ключ в одном из заголовков:

#### Способ 1: `X-API-Key` (рекомендуется)

```http
X-API-Key: mk_live_Xk9mP2vQ7rT4wL8nZ3sY6tB1cD5fG0hJ
```

#### Способ 2: `Authorization: Bearer`

```http
Authorization: Bearer mk_live_Xk9mP2vQ7rT4wL8nZ3sY6tB1cD5fG0hJ
```

Оба способа равнозначны. При отсутствии или невалидности ключа сервер вернёт `401 Unauthorized` с ошибкой `invalid_api_key`.

### 2. Сессия (для веб-интерфейса и защищённых эндпоинтов)

Для веб-интерфейса и защищённых эндпоинтов (API-ключи, биллинг, история, профиль) используется HTTP-сессия:

- Cookie: `session_id` (UUID)
- Устанавливается при регистрации/логине
- Живёт 30 дней
- Передаётся автоматически браузером

---

## 🔄 Конвертация URL в Markdown

Основной эндпоинт API. Доступен **анонимам** и **пользователям с API-ключом**.

### Запрос

```http
POST /api/convert
Content-Type: application/json
X-API-Key: mk_live_YOUR_KEY_HERE
```

> **Примечание:** Для анонимов API-ключ не нужен, но в этом случае применяется IP-лимит (3 запроса/24 часа).

### Тело запроса

```json
{
  "url": "https://example.com/article",
  "include_title": true,
  "include_frontmatter": false,
  "include_toc": false,
  "strip_images": false,
  "strip_links": false
}
```

| Поле | Тип | Обязательное | По умолчанию | Описание |
|------|-----|:------------:|:------------:|----------|
| `url` | string | ✅ | — | URL веб-страницы для конвертации (http/https) |
| `include_title` | bool | ❌ | `false` | Добавить заголовок страницы как H1 (`# Title`) |
| `include_frontmatter` | bool | ❌ | `false` | Добавить YAML-шапку с метаданными |
| `include_toc` | bool | ❌ | `false` | Добавить оглавление (Table of Contents) |
| `strip_images` | bool | ❌ | `false` | Удалить все `<img>` теги |
| `strip_links` | bool | ❌ | `false` | Удалить `<a>` теги (текст сохраняется) |

### Успешный ответ (200 OK)

```json
{
  "title": "Example Article",
  "content": "# Example Article\n\nThis is the converted content...",
  "metadata": {
    "words": 4521,
    "tokens": 1234,
    "bytes": 4521
  },
  "quota_incremented": true
}
```

| Поле | Тип | Описание |
|------|-----|----------|
| `title` | string | Заголовок страницы (может отсутствовать) |
| `content` | string | Результат конвертации в Markdown |
| `metadata.words` | int | Количество слов в контенте |
| `metadata.tokens` | int | Количество токенов (для LLM, cl100k) |
| `metadata.bytes` | int | Размер в байтах |
| `quota_incremented` | bool | `true` — списан кредит; `false` — cache hit или лимит |

### Пример cURL

```bash
curl -X POST https://markclean.online/api/convert \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mk_live_YOUR_KEY_HERE" \
  -d '{
    "url": "https://metanit.com/web/html5/2.6.php",
    "include_title": true,
    "include_frontmatter": true,
    "strip_images": true,
    "strip_links": false
  }'
```

---

## 📚 История конвертаций

Получить список всех конвертаций текущего пользователя с пагинацией.

**Требует авторизации** (API-ключ или сессия).

### Запрос

```http
GET /api/converter/history?page=1&page_size=20
X-API-Key: mk_live_YOUR_KEY_HERE
```

| Параметр | Тип | По умолчанию | Описание |
|----------|-----|:------------:|----------|
| `page` | int | `1` | Номер страницы (≥ 1) |
| `page_size` | int | `20` | Количество записей (1–100) |

### Успешный ответ (200 OK)

```json
{
  "items": [
    {
      "id": "27c1e865-a77e-4d99-87d0-1179aef2a3e6",
      "title": "Example Article",
      "target_url": "https://example.com/article",
      "updated_at": "2026-09-27T14:30:00Z"
    }
  ],
  "total_count": 42,
  "page": 1,
  "page_size": 20,
  "has_more": true
}
```

| Поле | Тип | Описание |
|------|-----|----------|
| `items` | array | Список конвертаций (отсортированы по `updated_at` DESC) |
| `items[].id` | string | UUID записи |
| `items[].title` | string | Заголовок страницы (или пустая строка) |
| `items[].target_url` | string | Исходный URL |
| `items[].updated_at` | string | Последняя конвертация (ISO 8601) |
| `total_count` | int | Общее количество записей (только успешные, status_code = 200) |
| `page` | int | Текущая страница |
| `page_size` | int | Размер страницы |
| `has_more` | bool | Есть ли следующие страницы |

> 💡 **Дедупликация:** Один URL = одна запись. Повторные конвертации обновляют `updated_at` и перемещают запись наверх.

---

## 🎛️ Опции конвертации

### `include_title: true`

Добавляет заголовок страницы как H1 в начало документа:

```markdown
# Example Article

This is the content...
```

### `include_frontmatter: true`

Добавляет YAML-шапку с метаданными (удобно для статических генераторов типа Hugo/Jekyll):

```markdown
---
title: "Example Article"
source: "https://example.com/article"
language: "English"
words: 4521
tokens: 1234
bytes: 4521
reading_time: "23 min"
extracted_at: "2026-09-27"
---

# Example Article

This is the content...
```

Поле `language` определяется автоматически через `whatlanggo` (только если включён `include_toc` или `include_frontmatter`).

### `include_toc: true`

Добавляет оглавление (Table of Contents) из заголовков H1–H3:

```markdown
## Table of Contents

- [Main Section](<#Main Section>)
- [Subsection](<#Subsection>)

# Main Section

Content...
```

> ⚠️ Оглавление добавляется только если заголовков H1–H3 **не менее 2**. Иначе оглавление не включается.

### `strip_images: true`

Полностью удаляет все `<img>` теги. Полезно для:
- 🤖 Подготовки текста для LLM (экономия токенов)
- 📄 Создания текстовых версий статей
- 💾 Уменьшения размера результата

### `strip_links: true`

Удаляет `<a>` теги, но **сохраняет текст ссылок**:

**Было:**
```html
Visit <a href="https://example.com">our site</a> for more info.
```

**Стало:**
```markdown
Visit our site for more info.
```

### 🎯 Рекомендуемые комбинации

| Сценарий | Опции |
|----------|-------|
| **Для LLM / RAG** | `strip_images: true`, `strip_links: true` |
| **Для документации** | `include_title: true`, `include_frontmatter: true` |
| **Для архивирования** | `include_title: true`, `include_frontmatter: true`, `strip_images: false` |
| **Минимальный размер** | `strip_images: true`, `strip_links: true`, `include_title: false` |

---

## 🔑 API-ключи

Управление API-ключами — **только через сессию** (веб-интерфейс). API-ключами нельзя управлять через API.

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

**POST** `/api/keys`

**Запрос:**
```json
{
  "name": "My Key"
}
```
`name` необязательно (макс. 50 символов). Если не указан, используется `"Default Key"`.

**Ответ (201 Created):**
```json
{
  "id": "27c1e865-a77e-4d99-87d0-1179aef2a3e6",
  "name": "My Key",
  "api_key": "mk_live_Xk9mP2vQ7rT4wL8nZ3sY6tB1cD5fG0hJ",
  "warning": "Save this key now. It will not be shown again."
}
```

> ⭐ Сырой ключ возвращается **только в этом ответе**. Больше его никто не покажет.

**Ошибки:**
- `409 Conflict` + `key_already_exists` — ключ уже существует (у пользователя только 1 ключ)
- `500 Internal Server Error` + `internal_error`

### Получение метаданных ключа

**GET** `/api/keys`

**Ответ (200 OK):**
```json
{
  "id": "27c1e865-a77e-4d99-87d0-1179aef2a3e6",
  "name": "My Key",
  "key_prefix": "mk_live_a1b2c3d4",
  "last_used_at": "2026-09-27 10:30:00",
  "is_active": true,
  "created_at": "2026-09-27 09:00:00"
}
```

**Ошибки:**
- `404 Not Found` + `key_not_found` — у пользователя нет ключа

### Удаление ключа

**DELETE** `/api/keys/:key_id`

**Ответ (200 OK):**
```json
{
  "message": "API key deleted successfully"
}
```

**Ошибки:**
- `400 Bad Request` + `invalid_key_id` — некорректный UUID
- `404 Not Found` + `key_not_found` — ключ не найден
- `500 Internal Server Error` + `internal_error`

---

## 💳 Биллинг: пакеты и подписки

### Получение доступных пакетов

**GET** `/api/billing/packages` — **публичный** эндпоинт (авторизация не требуется).

**Ответ (200 OK):**
```json
{
  "free": {
    "name": "Free",
    "daily_limit": 10
  },
  "credits": [
    {
      "code": "micro",
      "name": "Micro",
      "credits": 300,
      "price": 49,
      "price_per_100_requests": 17,
      "discount": 0,
      "savings_rub": 0,
      "is_popular": false
    },
    {
      "code": "start",
      "name": "Start",
      "credits": 1000,
      "price": 99,
      "price_per_100_requests": 9,
      "discount": 32,
      "savings_rub": 17,
      "is_popular": false
    },
    {
      "code": "optimal",
      "name": "Optimal",
      "credits": 3000,
      "price": 199,
      "price_per_100_requests": 7,
      "discount": 42,
      "savings_rub": 27,
      "is_popular": true
    },
    {
      "code": "pro",
      "name": "Pro",
      "credits": 8000,
      "price": 399,
      "price_per_100_requests": 5,
      "discount": 51,
      "savings_rub": 57,
      "is_popular": false
    },
    {
      "code": "ultra",
      "name": "Ultra",
      "credits": 20000,
      "price": 799,
      "price_per_100_requests": 4,
      "discount": 63,
      "savings_rub": 124,
      "is_popular": false
    }
  ],
  "subscriptions": [
    {
      "months": 1,
      "discount_percent": 0,
      "total_price": 499,
      "monthly_price": 499,
      "savings_rub": 0
    },
    {
      "months": 3,
      "discount_percent": 5,
      "total_price": 1419,
      "monthly_price": 473,
      "savings_rub": 78
    },
    {
      "months": 6,
      "discount_percent": 10,
      "total_price": 2690,
      "monthly_price": 448,
      "savings_rub": 304
    },
    {
      "months": 12,
      "discount_percent": 19,
      "total_price": 4790,
      "monthly_price": 399,
      "savings_rub": 1198
    }
  ]
}
```

| Поле | Описание |
|------|----------|
| `free` | Бесплатный план: дневной лимит |
| `credits[]` | Пакеты кредитов (от дешёвого к дорогому) |
| `credits[].code` | Код пакета (`micro`, `start`, `optimal`, `pro`, `ultra`) |
| `credits[].credits` | Количество кредитов в пакете |
| `credits[].price` | Цена в рублях |
| `credits[].price_per_100_requests` | Стоимость 100 запросов |
| `credits[].discount` | Процент выгоды (от базового тарифа Micro) |
| `credits[].savings_rub` | Экономия в рублях |
| `credits[].is_popular` | Флаг «Хит» |
| `subscriptions[]` | Пакеты подписки (от короткого к длинному) |

### Покупка пакета

**POST** `/api/billing/purchase` — **требует авторизации** (API-ключ или сессия).

> ⚠️ **Временный endpoint!** В продакшене будет заменён на реальную интеграцию с платёжной системой.

**Запрос:**
```json
{
  "package_code": "optimal"
}
```

**Ответ (200 OK):**
```json
{
  "message": "Credits added successfully",
  "package": "optimal",
  "credits_added": 3000,
  "new_balance": 3000
}
```

**Ошибки:**
- `400 Bad Request` + `invalid_package` — некорректный код пакета
- `401 Unauthorized` + `unauthorized` — нет аутентификации
- `500 Internal Server Error` + `purchase_failed` — ошибка начисления кредитов

---

## 📊 Проверка баланса

### Получение баланса кредитов и подписки

**GET** `/api/billing/usage` — **требует авторизации** (API-ключ или сессия).

**Ответ (200 OK):**
```json
{
  "credits": {
    "credits": 2500,
    "daily_used": 3,
    "daily_limit": 10,
    "daily_remaining": 7,
    "has_credits": true,
    "daily_reset_at": "2026-09-27T14:00:00Z"
  },
  "subscription": {
    "is_active": true,
    "ends_at": "2026-10-01T10:00:00Z",
    "days_remaining": 4,
    "is_unlimited": true
  },
  "is_subscriber": true
}
```

| Поле | Тип | Описание |
|------|-----|----------|
| `credits` | object | Баланс кредитов |
| `credits.credits` | int | Платные кредиты (не сгорают) |
| `credits.daily_used` | int | Использовано запросов сегодня |
| `credits.daily_limit` | int | Дневной лимит (10) |
| `credits.daily_remaining` | int | Осталось запросов сегодня |
| `credits.has_credits` | bool | Есть ли платные кредиты |
| `credits.daily_reset_at` | time | Время следующего сброса дневного лимита |
| `subscription` | object/null | Информация об активной подписке |
| `subscription.is_active` | bool | Подписка активна |
| `subscription.ends_at` | time | Дата окончания подписки |
| `subscription.days_remaining` | int | Осталось дней |
| `subscription.is_unlimited` | bool | Безлимит (всегда true) |
| `is_subscriber` | bool | Есть ли активная подписка |

---

## ⚠️ Обработка ошибок

Все ошибки возвращаются в едином формате:

```json
{
  "error": "machine_readable_code",
  "message": "Human-readable description"
}
```

### HTTP-статусы

| Статус | Код ошибки | Описание | Действие |
|:------:|------------|----------|----------|
| `400` | `invalid_payload` | Битый JSON или отсутствует `url` | Проверьте тело запроса |
| `400` | `invalid_url` | Некорректный формат URL | Должен начинаться с `http://` или `https://` |
| `400` | `invalid_request` | Некорректный запрос (биллинг) | Проверьте параметры |
| `400` | `invalid_package` | Неверный код пакета | Используйте валидный код |
| `401` | `invalid_api_key` | Ключ отсутствует, невалиден или удалён | Проверьте заголовок `X-API-Key` |
| `401` | `unauthorized` | Нет аутентификации | Передайте API-ключ или cookie |
| `402` | `quota_exceeded` | Кредиты закончились + дневной лимит | Купите кредиты в веб-интерфейсе |
| `404` | `key_not_found` | Ключ не найден | Создайте ключ заново |
| `404` | `key_not_found` | Ключ пользователя не найден (GET /api/keys) | Создайте ключ |
| `404` | `user_not_found` | Пользователь не найден | Проверьте данные |
| `409` | `key_already_exists` | У пользователя уже есть API-ключ | Удалите существующий ключ |
| `409` | `user_exists` | Пользователь с этим email уже зарегистрирован | Используйте другой email |
| `409` | `account_already_deleted` | Аккаунт уже удалён | — |
| `410` | `email_previously_deleted` | Email был использован для удалённого аккаунта | Используйте другой email |
| `415` | `unsupported_content` | URL не возвращает HTML | API работает только с веб-страницами |
| `422` | `conversion_failed` | Не удалось распознать контент | Попробуйте другой URL |
| `429` | `rate_limit_exceeded` | Превышен лимит запросов | Подождите или войдите в аккаунт |
| `429` | `registration_ip_limit` | Превышен лимит регистраций с IP | Подождите |
| `429` | `resend_cooldown` | Слишком часто запрашивается OTP | Подождите |
| `429` | `otp_blocked` | Слишком много неудачных попыток OTP | Запросите новый код |
| `429` | `registration_ip_limit` | Превышен лимит регистраций с IP | Подождите |
| `429` | `registration_ip_limit` | Превышен лимит регистраций с IP | Подождите |
| `500` | `internal_server_error` | Внутренняя ошибка сервера | Повторите позже |
| `502` | `fetch_failed` | Не удалось загрузить страницу | Сайт недоступен или заблокировал запрос |

### Пример обработки ошибки

```bash
$ curl -X POST https://markclean.online/api/convert \
    -H "X-API-Key: mk_live_INVALID" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com"}'

HTTP/1.1 401 Unauthorized
{
  "error": "invalid_api_key",
  "message": "Invalid or expired API key"
}
```

---

## 📊 Квоты, лимиты и кэширование

### Система кредитов

- 💳 **Платные кредиты** — не сгорают, не имеют срока действия
- 📅 **Дневной лимит** (10 запросов/сутки) — сбрасывается каждые 24 часа
- ⚡ **Приоритет списания:** сначала платные кредиты, затем дневной лимит
- 📊 **Максимальный баланс:** 500 000 кредитов

### Кэширование и экономия

API использует **двухуровневое кэширование**:

| Уровень | Что кэшируется | TTL | Экономия |
|---------|----------------|-----|----------|
| **L1** | Сырой HTML | 30 мин | Нет HTTP-запроса к внешнему сайту |
| **L2** | Финальный Markdown | 15 мин | Мгновенный ответ |

**Важно:** Кредиты списываются **только** при реальном HTTP-запросе к внешнему сайту. Повторные конвертации того же URL (даже с другими опциями) **бесплатны**, если HTML ещё в кэше.

### Таблица сценариев

| Сценарий | Fetch | Кредиты | Скорость |
|----------|:-----:|:-------:|----------|
| Первый запрос URL | ✅ | −1 | ~2-5 сек |
| Повтор с теми же опциями | ❌ | 0 | ~50 мс |
| Повтор с другими опциями | ❌ | 0 | ~200 мс |
| Спустя 30+ минут | ✅ | −1 | ~2-5 сек |

### IP-лимиты (для анонимов)

- **Конвертация:** 3 запроса / 24 часа с одного IP
- **Регистрация:** 3 регистрации / 1 час с одного IP (глобально), 3 регистрации / 2 минуты с одного IP
- **Логин:** 10 попыток / 30 минут с одного IP, 5 попыток / 15 минут на email
- **Recovery OTP:** 10 попыток / 1 час с одного IP
- **OTP Verify:** 20 попыток / 5 минут с одного IP
- **Смена пароля:** 5 попыток / 1 час с одного IP, 3 попытки / 1 час на пользователя

### Проверка баланса

Для проверки баланса кредитов используйте:
- Веб-интерфейс (страница **Billing**)
- API: **GET** `/api/billing/usage` (требует авторизации)

---

## 💻 Примеры кода

### Python (requests)

```python
import requests

API_KEY = "mk_live_YOUR_KEY_HERE"
API_BASE = "https://markclean.online/api"

headers = {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY,
}

# Конвертация
response = requests.post(
    f"{API_BASE}/convert",
    headers=headers,
    json={
        "url": "https://example.com/article",
        "include_title": True,
        "include_frontmatter": True,
        "strip_images": True,
        "strip_links": False,
    },
)

if response.ok:
    data = response.json()
    print(f"Title: {data.get('title')}")
    print(f"Words: {data['metadata']['words']}")
    print(f"Tokens: {data['metadata']['tokens']}")
    print(f"Credits used: {data['quota_incremented']}")
    print(data["content"][:500])
else:
    error = response.json()
    print(f"Error {response.status_code}: {error['error']} - {error['message']}")
```

### Python (пакетная конвертация)

```python
import requests
import time

API_KEY = "mk_live_YOUR_KEY_HERE"
urls = [
    "https://example.com/page1",
    "https://example.com/page2",
    "https://example.com/page3",
]

headers = {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY,
}

results = []
for url in urls:
    resp = requests.post(
        "https://markclean.online/api/convert",
        headers=headers,
        json={"url": url, "include_title": True},
    )
    if resp.ok:
        results.append(resp.json())
        print(f"✅ {url}")
    else:
        print(f"❌ {url}: {resp.json()['error']}")
    time.sleep(0.5)  # Вежливый delay

# Сохраняем в один файл
with open("output.md", "w", encoding="utf-8") as f:
    for r in results:
        f.write(r["content"] + "\n\n---\n\n")
```

### JavaScript / Node.js (fetch)

```javascript
const API_KEY = 'mk_live_YOUR_KEY_HERE';
const API_BASE = 'https://markclean.online/api';

async function convertUrl(url, options = {}) {
  const response = await fetch(`${API_BASE}/convert`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
    },
    body: JSON.stringify({
      url,
      include_title: options.title ?? false,
      include_frontmatter: options.frontmatter ?? false,
      include_toc: options.toc ?? false,
      strip_images: options.stripImages ?? false,
      strip_links: options.stripLinks ?? false,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.error}: ${error.message}`);
  }

  return response.json();
}

// Использование
try {
  const result = await convertUrl('https://example.com/article', {
    title: true,
    frontmatter: true,
    stripImages: true,
  });
  console.log(result.content);
} catch (err) {
  console.error('Conversion failed:', err.message);
}
```

### Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

const (
    apiKey  = "mk_live_YOUR_KEY_HERE"
    apiBase = "https://markclean.online/api"
)

type ConvertRequest struct {
    URL                string `json:"url"`
    IncludeTitle       bool   `json:"include_title"`
    IncludeFrontmatter bool   `json:"include_frontmatter"`
    IncludeTOC         bool   `json:"include_toc"`
    StripImages        bool   `json:"strip_images"`
    StripLinks         bool   `json:"strip_links"`
}

type Metadata struct {
    Words  int `json:"words"`
    Tokens int `json:"tokens"`
    Bytes  int `json:"bytes"`
}

type ConvertResponse struct {
    Title            string `json:"title"`
    Content          string `json:"content"`
    Metadata         Metadata `json:"metadata"`
    QuotaIncremented bool   `json:"quota_incremented"`
}

func main() {
    reqBody, _ := json.Marshal(ConvertRequest{
        URL:                "https://example.com/article",
        IncludeTitle:       true,
        IncludeFrontmatter: true,
        StripImages:        true,
        StripLinks:         false,
    })

    req, _ := http.NewRequest("POST", apiBase+"/convert", bytes.NewReader(reqBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", apiKey)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    if resp.StatusCode != http.StatusOK {
        fmt.Printf("Error %d: %s\n", resp.StatusCode, body)
        return
    }

    var result ConvertResponse
    json.Unmarshal(body, &result)
    fmt.Println(result.Content)
}
```

### cURL (все сценарии)

```bash
# Базовая конвертация
curl -X POST https://markclean.online/api/convert \
  -H "X-API-Key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Для LLM (чистый текст)
curl -X POST https://markclean.online/api/convert \
  -H "X-API-Key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "strip_images": true,
    "strip_links": true
  }'

# Для документации (с метаданными)
curl -X POST https://markclean.online/api/convert \
  -H "X-API-Key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "include_title": true,
    "include_frontmatter": true
  }'

# Для документации (с оглавлением)
curl -X POST https://markclean.online/api/convert \
  -H "X-API-Key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "include_title": true,
    "include_frontmatter": true,
    "include_toc": true
  }'

# История конвертаций
curl -X GET "https://markclean.online/api/converter/history?page=1&page_size=10" \
  -H "X-API-Key: mk_live_YOUR_KEY"

# Проверка баланса
curl -X GET "https://markclean.online/api/billing/usage" \
  -H "X-API-Key: mk_live_YOUR_KEY"

# Получить доступные пакеты
curl -X GET "https://markclean.online/api/billing/packages"
```

---

## ❓ FAQ

### 🔐 Безопасно ли передавать API-ключ?

**Да**, если соблюдаете правила:
- ✅ Используйте HTTPS (всегда)
- ✅ Храните ключ в переменных окружения, не в коде
- ✅ Не логируйте ключ
- ❌ Не коммитьте ключ в Git
- ❌ Не передавайте ключ в URL-параметрах

### 🔄 Что делать, если ключ скомпрометирован?

1. Откройте `/api-keys` в веб-интерфейсе
2. Нажмите **"Пересоздать"** (старый ключ будет удалён, создан новый)
3. Обновите ключ во всех ваших приложениях

> ⚠️ Старый ключ перестаёт работать мгновенно после пересоздания.

### 💳 Можно ли использовать API без кредитов?

Да, у каждого пользователя есть **бесплатный дневной лимит** (10 запросов/сутки), который сбрасывается каждые 24 часа. После исчерпания и дневного лимита, и кредитов — API вернёт `402 quota_exceeded`.

### ⚡ Почему `quota_incremented: false`?

Это нормально в трёх случаях:
1. **Cache hit** — этот URL уже конвертировался недавно (бесплатно)
2. **Анонимный запрос** — без API-ключа (лимит по IP)
3. **Подписка** — у пользователя активна подписка, кредиты не списываются

### 🌍 Работает ли API с любым сайтом?

API работает с любыми **публично доступными HTML-страницами**. Ограничения:
- ❌ Сайты, требующие авторизации
- ❌ Сайты с жёсткой анти-бот защитой (Cloudflare challenge и т.п.)
- ❌ PDF, изображения и другие не-HTML форматы
- ❌ Сайты, блокирующие по User-Agent

### 📦 Есть ли лимит на размер страницы?

- Максимум: **5 MB** контента после конвертации
- Типичные статьи: 10-100 KB
- Длинные технические документы: 200-500 KB

Страницы больше 5 MB не кэшируются, но всё равно конвертируются.

### 🔗 Как использовать API-ключ с другими инструментами?

**Postman:**
- Вкладка **Authorization** → Type: **API Key**
- Key: `X-API-Key`, Value: ваш ключ, Add to: **Header**

**Insomnia:**
- Request → **Auth** → **API Key**
- Header name: `X-API-Key`

**VS Code (REST Client):**
```http
@apiKey = mk_live_YOUR_KEY

POST https://markclean.online/api/convert
Content-Type: application/json
X-API-Key: {{apiKey}}

{
  "url": "https://example.com"
}
```

### 🗑️ Что будет с API-ключом после удаления аккаунта?

**Ключ продолжит работать**, пока не закончатся кредиты. После удаления аккаунта:
- ✅ API-ключ остаётся активным
- ✅ Существующие кредиты можно использовать
- ❌ Пополнить кредиты нельзя (нет доступа к UI)
- ❌ Создать новый ключ нельзя

Это сделано для честности: вы оплатили кредиты — вы их используете.

### 🛠️ Есть ли SDK?

Официальных SDK пока нет, но API достаточно простой для использования через стандартные HTTP-клиенты в любом языке. Примеры выше покрывают самые популярные языки.

---

## 📞 Поддержка

- 📧 **Email:** gnutenko.s.r@gmail.com
- 💬 **Telegram:** [@Slayder12](https://t.me/Slayder12)
- 📝 **Changelog:** [markclean-doc/changelog.md](https://gitea.gsrhost.ru/gsr/markclean-doc/src/branch/main/changelog.md)

---

**Последнее обновление:** 10 октября 2026  
**Версия API:** `v1`