# SmartPDF API

> 24 операции с PDF по HTTP и MCP: конвертация в PDF и из PDF, сжатие, объединение и разделение, распознавание текста (OCR, в том числе русский), страницы, подпись, водяной знак, пароль. REST: https://api.smartpdf.ru/v1, ключ — заголовок X-API-Key. MCP: https://mcp.smartpdf.ru/mcp, ключ — Authorization: Bearer. Оплата с баланса API в рублях за запрос.

Все операции асинхронные: POST /v1/upload (multipart, поле file) → file_id; POST /v1/pdf/<операция> (JSON с file_id и параметрами) → task_id; GET /v1/tasks/{task_id} до status = done; GET /v1/tasks/{task_id}/download → download_url (действует час). Ключ создаётся в личном кабинете: https://smartpdf.ru/dashboard/api-keys.

## Начало

- [Введение](https://dev.smartpdf.ru/docs/index.md): Что умеет API SmartPDF, базовый адрес, форматы и как устроена работа.
- [Быстрый старт](https://dev.smartpdf.ru/docs/quickstart.md): Первый запрос: ключ, загрузка, операция, ожидание, скачивание — на 7 языках.
- [Ключи и авторизация](https://dev.smartpdf.ru/docs/auth.md): Заголовок X-API-Key, лимиты трат и перевыпуск ключей.
- [Как это работает](https://dev.smartpdf.ru/docs/how-it-works.md): Жизненный цикл операции, статусы задач, хранение файлов и имена результатов.

## API

- [Загрузка файлов](https://dev.smartpdf.ru/docs/upload.md): POST /v1/upload: форматы, размеры по тарифу, срок жизни file_id.
- [Операции](https://dev.smartpdf.ru/docs/operations.md): Все 24 операции: адреса, параметры и единицы цены.
- [Статус и скачивание](https://dev.smartpdf.ru/docs/tasks.md): GET /v1/tasks/{task_id} и ссылка на результат.
- [Вебхуки](https://dev.smartpdf.ru/docs/webhooks.md): Уведомление о готовности вместо опроса, проверка подписи HMAC-SHA256.
- [Ошибки](https://dev.smartpdf.ru/docs/errors.md): Коды ответов и что с ними делать.
- [Лимиты](https://dev.smartpdf.ru/docs/limits.md): Частота запросов, размеры файлов, страницы, время обработки.
- [Оплата](https://dev.smartpdf.ru/docs/billing.md): Баланс в рублях, цена запроса, страницы тяжёлых операций, бонусы и включённые запросы Бизнеса.

## Операции

- [Word в PDF](https://dev.smartpdf.ru/docs/operations/word-to-pdf.md): /v1/pdf/word-to-pdf — Конвертирует документ Word в PDF: шрифты, таблицы и кириллица сохраняются.
- [JPG в PDF](https://dev.smartpdf.ru/docs/operations/jpg-to-pdf.md): /v1/pdf/jpg-to-pdf — Собирает PDF из изображений: каждое — отдельная страница.
- [Excel в PDF](https://dev.smartpdf.ru/docs/operations/xlsx-to-pdf.md): /v1/pdf/xlsx-to-pdf — Конвертирует таблицу Excel в PDF. Листы, область и масштаб берутся из параметров печати файла.
- [PowerPoint в PDF](https://dev.smartpdf.ru/docs/operations/pptx-to-pdf.md): /v1/pdf/pptx-to-pdf — Конвертирует презентацию PowerPoint в PDF: слайд — страница.
- [HTML в PDF](https://dev.smartpdf.ru/docs/operations/html-to-pdf.md): /v1/pdf/html-to-pdf — Превращает HTML-файл в PDF. Внешние ресурсы не загружаются: картинки и шрифты — только встроенные (data:), стили — в самом файле.
- [PDF в Word](https://dev.smartpdf.ru/docs/operations/pdf-to-word.md): /v1/pdf/to-word — Конвертирует PDF в редактируемый документ Word. Сканы без текстового слоя сначала распознайте (OCR).
- [PDF в Excel](https://dev.smartpdf.ru/docs/operations/pdf-to-excel.md): /v1/pdf/to-excel — Извлекает таблицы из PDF в Excel.
- [PDF в PowerPoint](https://dev.smartpdf.ru/docs/operations/pdf-to-pptx.md): /v1/pdf/to-pptx — Конвертирует PDF в презентацию PowerPoint: каждая страница — отдельный слайд.
- [PDF в JPG](https://dev.smartpdf.ru/docs/operations/pdf-to-jpg.md): /v1/pdf/to-jpg — Сохраняет страницы PDF картинками JPG. Результат — ZIP-архив: page-1.jpg, page-2.jpg…
- [PDF в текст](https://dev.smartpdf.ru/docs/operations/pdf-to-txt.md): /v1/pdf/to-txt — Извлекает текст из PDF в файл TXT (UTF-8).
- [Объединить PDF](https://dev.smartpdf.ru/docs/operations/merge.md): /v1/pdf/merge — Объединяет несколько PDF в один. Цена — по суммарному размеру файлов.
- [Разделить PDF](https://dev.smartpdf.ru/docs/operations/split.md): /v1/pdf/split — Разделяет PDF на части. Результат — ZIP-архив с PDF-файлами.
- [Сжать PDF](https://dev.smartpdf.ru/docs/operations/compress.md): /v1/pdf/compress — Уменьшает размер PDF. Результат никогда не больше исходного файла.
- [Распознать текст](https://dev.smartpdf.ru/docs/operations/ocr.md): /v1/pdf/ocr — Распознаёт текст в сканах и добавляет невидимый текстовый слой: PDF можно искать и копировать. До 100 страниц за раз.
- [Сгладить PDF](https://dev.smartpdf.ru/docs/operations/flatten.md): /v1/pdf/flatten — Впечатывает поля форм и пометки в страницы: документ выглядит так же, но его нельзя отредактировать.
- [Повернуть страницы](https://dev.smartpdf.ru/docs/operations/rotate.md): /v1/pdf/rotate — Поворачивает страницы PDF.
- [Удалить страницы](https://dev.smartpdf.ru/docs/operations/delete-pages.md): /v1/pdf/delete-pages — Удаляет страницы из PDF — полностью, вместе с их содержимым.
- [Извлечь страницы](https://dev.smartpdf.ru/docs/operations/extract-pages.md): /v1/pdf/extract-pages — Сохраняет выбранные страницы в новый PDF в указанном порядке.
- [Порядок страниц](https://dev.smartpdf.ru/docs/operations/reorder-pages.md): /v1/pdf/reorder-pages — Меняет порядок страниц. Неуказанные страницы добавляются в конец в исходном порядке.
- [Нумерация страниц](https://dev.smartpdf.ru/docs/operations/add-page-numbers.md): /v1/pdf/add-page-numbers — Добавляет номера страниц.
- [Подписать PDF](https://dev.smartpdf.ru/docs/operations/sign.md): /v1/pdf/sign — Ставит на страницу визуальную подпись — текст или изображение. Это не электронная подпись (ЭП).
- [Защитить паролем](https://dev.smartpdf.ru/docs/operations/protect.md): /v1/pdf/protect — Ставит пароль на открытие PDF (AES-256).
- [Снять пароль](https://dev.smartpdf.ru/docs/operations/unlock.md): /v1/pdf/unlock — Снимает пароль с PDF, если пароль известен.
- [Водяной знак](https://dev.smartpdf.ru/docs/operations/watermark.md): /v1/pdf/watermark — Наносит водяной знак — текст или логотип. Нужен ровно один из параметров text и image_file_id.

## MCP и агенты

- [MCP-сервер](https://dev.smartpdf.ru/docs/mcp.md): Адрес, ключ, инструменты и цена — подключение ИИ-агентов.
- [Как передать файл](https://dev.smartpdf.ru/docs/files.md): Публичные ссылки для MCP и загрузка файлов с компьютера через REST.
- [Claude Code](https://dev.smartpdf.ru/docs/claude-code.md): Плагин SmartPDF или команда claude mcp add; ключ — из переменной окружения.
- [Claude Desktop](https://dev.smartpdf.ru/docs/claude-desktop.md): Коннектор с заголовком или конфиг через mcp-remote.
- [Cursor](https://dev.smartpdf.ru/docs/cursor.md): mcp.json с ключом из переменной окружения.
- [VS Code](https://dev.smartpdf.ru/docs/vscode.md): mcp.json для агента Copilot, ключ — защищённым вводом.
- [Codex CLI](https://dev.smartpdf.ru/docs/codex.md): config.toml и bearer_token_env_var.
- [Gemini CLI](https://dev.smartpdf.ru/docs/gemini.md): settings.json, поле httpUrl.
- [Windsurf и Cline](https://dev.smartpdf.ru/docs/other-clients.md): Конфиги для Devin Desktop (Windsurf) и Cline.
- [n8n](https://dev.smartpdf.ru/docs/n8n.md): Узел MCP Client Tool или HTTP Request к REST API.
- [Make](https://dev.smartpdf.ru/docs/make.md): Приложение MCP Client или модуль HTTP с REST API.

## Справочник

- [OpenAPI и Postman](https://dev.smartpdf.ru/docs/openapi.md): Схема OpenAPI, коллекция Postman и Swagger.

## Optional

- [OpenAPI](https://dev.smartpdf.ru/openapi.json): схема публичных запросов
- [Postman](https://dev.smartpdf.ru/postman.json): коллекция запросов