# SmartPDF API

> 47 операций с PDF и фото по HTTP и MCP: конвертация в PDF и из PDF (в том числе Markdown, DjVu, FB2, EPUB), сжатие, объединение и разделение, распознавание текста (OCR, в том числе русский), редактор PDF, поиск и удаление персональных данных, страницы, подпись, водяной знак, пароль, инструменты для фото. 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://smartpdf.ru/developers/docs/index.md): Что умеет API SmartPDF, базовый адрес, форматы и как устроена работа.
- [Быстрый старт](https://smartpdf.ru/developers/docs/quickstart.md): Первый запрос: ключ, загрузка, операция, ожидание, скачивание — на 7 языках.
- [Ключи и авторизация](https://smartpdf.ru/developers/docs/auth.md): Заголовок X-API-Key, лимиты трат и перевыпуск ключей.
- [Как это работает](https://smartpdf.ru/developers/docs/how-it-works.md): Жизненный цикл операции, статусы задач, хранение файлов и имена результатов.

## API

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

## Операции

- [Word в PDF](https://smartpdf.ru/developers/docs/operations/word-to-pdf.md): /v1/pdf/word-to-pdf — Конвертирует документ Word в PDF: шрифты, таблицы и кириллица сохраняются.
- [JPG в PDF](https://smartpdf.ru/developers/docs/operations/jpg-to-pdf.md): /v1/pdf/jpg-to-pdf — Собирает PDF из изображений: каждое — отдельная страница.
- [Excel в PDF](https://smartpdf.ru/developers/docs/operations/xlsx-to-pdf.md): /v1/pdf/xlsx-to-pdf — Конвертирует таблицу Excel в PDF. Листы, область и масштаб берутся из параметров печати файла.
- [PowerPoint в PDF](https://smartpdf.ru/developers/docs/operations/pptx-to-pdf.md): /v1/pdf/pptx-to-pdf — Конвертирует презентацию PowerPoint в PDF: слайд — страница.
- [HTML в PDF](https://smartpdf.ru/developers/docs/operations/html-to-pdf.md): /v1/pdf/html-to-pdf — Превращает HTML-файл в PDF. Внешние ресурсы не загружаются: картинки и шрифты — только встроенные (data:), стили — в самом файле.
- [PDF в Word](https://smartpdf.ru/developers/docs/operations/pdf-to-word.md): /v1/pdf/to-word — Конвертирует PDF в редактируемый документ Word. Скан без текстового слоя (у загрузки text_layer: false) — с ocr: true: текст распознаётся и собирается в Word абзацами.
- [PDF в Excel](https://smartpdf.ru/developers/docs/operations/pdf-to-excel.md): /v1/pdf/to-excel — Извлекает таблицы из PDF в Excel.
- [PDF в PowerPoint](https://smartpdf.ru/developers/docs/operations/pdf-to-pptx.md): /v1/pdf/to-pptx — Конвертирует PDF в презентацию PowerPoint: каждая страница — отдельный слайд.
- [PDF в JPG](https://smartpdf.ru/developers/docs/operations/pdf-to-jpg.md): /v1/pdf/to-jpg — Сохраняет страницы PDF картинками JPG. Результат — ZIP-архив: page-1.jpg, page-2.jpg…
- [PDF в текст](https://smartpdf.ru/developers/docs/operations/pdf-to-txt.md): /v1/pdf/to-txt — Извлекает текст из PDF в файл TXT (UTF-8).
- [Объединить PDF](https://smartpdf.ru/developers/docs/operations/merge.md): /v1/pdf/merge — Объединяет несколько PDF в один. Цена — по суммарному размеру файлов.
- [Разделить PDF](https://smartpdf.ru/developers/docs/operations/split.md): /v1/pdf/split — Разделяет PDF на части. Результат — ZIP-архив с PDF-файлами.
- [Сжать PDF](https://smartpdf.ru/developers/docs/operations/compress.md): /v1/pdf/compress — Уменьшает размер PDF. Результат никогда не больше исходного файла.
- [Распознать текст](https://smartpdf.ru/developers/docs/operations/ocr.md): /v1/pdf/ocr — Распознаёт текст в сканах и добавляет невидимый текстовый слой: PDF можно искать и копировать. До 100 страниц за раз.
- [Сгладить PDF](https://smartpdf.ru/developers/docs/operations/flatten.md): /v1/pdf/flatten — Впечатывает поля форм и пометки в страницы: документ выглядит так же, но его нельзя отредактировать.
- [Повернуть страницы](https://smartpdf.ru/developers/docs/operations/rotate.md): /v1/pdf/rotate — Поворачивает страницы PDF.
- [Удалить страницы](https://smartpdf.ru/developers/docs/operations/delete-pages.md): /v1/pdf/delete-pages — Удаляет страницы из PDF — полностью, вместе с их содержимым.
- [Извлечь страницы](https://smartpdf.ru/developers/docs/operations/extract-pages.md): /v1/pdf/extract-pages — Сохраняет выбранные страницы в новый PDF в указанном порядке.
- [Порядок страниц](https://smartpdf.ru/developers/docs/operations/reorder-pages.md): /v1/pdf/reorder-pages — Меняет порядок страниц. Неуказанные страницы добавляются в конец в исходном порядке.
- [Нумерация страниц](https://smartpdf.ru/developers/docs/operations/add-page-numbers.md): /v1/pdf/add-page-numbers — Добавляет номера страниц.
- [Подписать PDF](https://smartpdf.ru/developers/docs/operations/sign.md): /v1/pdf/sign — Ставит на страницу визуальную подпись — текст или изображение. Это не электронная подпись (ЭП).
- [Защитить паролем](https://smartpdf.ru/developers/docs/operations/protect.md): /v1/pdf/protect — Ставит пароль на открытие PDF (AES-256).
- [Снять пароль](https://smartpdf.ru/developers/docs/operations/unlock.md): /v1/pdf/unlock — Снимает пароль с PDF, если пароль известен.
- [Водяной знак](https://smartpdf.ru/developers/docs/operations/watermark.md): /v1/pdf/watermark — Наносит водяной знак — текст или логотип. Нужен ровно один из параметров text и image_file_id.
- [Фото в PDF](https://smartpdf.ru/developers/docs/operations/photo-to-pdf.md): /v1/pdf/photo-to-pdf — Собирает фото с телефона в PDF: каждое фото — лист A4 в его ориентации, файл легче за счёт уменьшения. Режим «Скан документа» находит лист на фото, выравнивает перспективу и делает белый фон.
- [DjVu в PDF](https://smartpdf.ru/developers/docs/operations/djvu-to-pdf.md): /v1/pdf/djvu-to-pdf — Конвертирует книгу или скан DjVu в PDF. Текстовый слой DjVu не переносится — для поиска по тексту распознайте результат операцией OCR.
- [FB2 в PDF](https://smartpdf.ru/developers/docs/operations/fb2-to-pdf.md): /v1/pdf/fb2-to-pdf — Конвертирует книгу FB2 в PDF: главы — закладки, автор и название — в свойствах файла.
- [EPUB в PDF](https://smartpdf.ru/developers/docs/operations/epub-to-pdf.md): /v1/pdf/epub-to-pdf — Конвертирует книгу EPUB в PDF: главы из оглавления (toc.ncx) — закладки.
- [PDF в PNG](https://smartpdf.ru/developers/docs/operations/pdf-to-png.md): /v1/pdf/to-png — Сохраняет страницы PDF картинками PNG без потерь — для схем, чертежей и скриншотов. Результат — ZIP-архив.
- [PDF в Markdown](https://smartpdf.ru/developers/docs/operations/pdf-to-markdown.md): /v1/pdf/to-markdown — Конвертирует PDF в Markdown для нейросетей, баз знаний и документации: заголовки по размеру шрифта, списки, таблицы, ссылки, жирный и курсив. Номера страниц у края убираются.
- [Сжать фото](https://smartpdf.ru/developers/docs/operations/compress-image.md): /v1/pdf/compress-image — Сжимает фото: по уровню или до нужного размера в КБ. Одно фото — файл, несколько — ZIP-архив.
- [HEIC в JPG](https://smartpdf.ru/developers/docs/operations/heic-to-jpg.md): /v1/pdf/heic-to-jpg — Конвертирует фото HEIC/HEIF с iPhone в JPG с исходными цветами (ICC-профиль сохраняется). Одно фото — JPG, несколько — ZIP-архив.
- [Фото в текст](https://smartpdf.ru/developers/docs/operations/image-to-text.md): /v1/pdf/image-to-text — Распознаёт текст на фото и картинках: текст всех фото — в один файл, каждое фото с новой страницы.
- [PNG в JPG](https://smartpdf.ru/developers/docs/operations/png-to-jpg.md): /v1/pdf/png-to-jpg — Конвертирует картинки PNG в JPG. Прозрачность — белым фоном. Одна картинка — JPG, несколько — ZIP-архив.
- [JPG в PNG](https://smartpdf.ru/developers/docs/operations/jpg-to-png.md): /v1/pdf/jpg-to-png — Конвертирует картинки JPG в PNG. Без потерь. Одна картинка — PNG, несколько — ZIP-архив.
- [WEBP в JPG](https://smartpdf.ru/developers/docs/operations/webp-to-jpg.md): /v1/pdf/webp-to-jpg — Конвертирует картинки WEBP в JPG. Прозрачность — белым фоном, у анимации — первый кадр. Одна картинка — JPG, несколько — ZIP-архив.
- [Изменить размер фото](https://smartpdf.ru/developers/docs/operations/resize-image.md): /v1/pdf/resize-image — Меняет размер фото в процентах или пикселях, формат сохраняется. Одно фото — файл, несколько — ZIP-архив.
- [Обрезать фото](https://smartpdf.ru/developers/docs/operations/crop-image.md): /v1/pdf/crop-image — Обрезает фото по рамке, формат сохраняется.
- [Повернуть фото](https://smartpdf.ru/developers/docs/operations/rotate-image.md): /v1/pdf/rotate-image — Поворачивает и отражает фото, формат сохраняется. Одно фото — файл, несколько — ZIP-архив.
- [Word в JPG](https://smartpdf.ru/developers/docs/operations/word-to-jpg.md): /v1/pdf/word-to-jpg — Сохраняет страницы документа Word картинками JPG. Одна страница — JPG, несколько — ZIP-архив.
- [Редактор PDF](https://smartpdf.ru/developers/docs/operations/edit.md): /v1/pdf/edit — Добавляет на страницы текст, подпись, картинку, закрашивание (текст под ним удаляется из файла), пометки и фигуры, заменяет строки текста. Объекты впечатываются в страницы.
- [PDF в ч/б](https://smartpdf.ru/developers/docs/operations/grayscale.md): /v1/pdf/grayscale — Переводит PDF в оттенки серого — для печати и требований «только ч/б». Текст остаётся текстом: искать и копировать можно.
- [PDF в PDF/A](https://smartpdf.ru/developers/docs/operations/to-pdfa.md): /v1/pdf/to-pdfa — Конвертирует PDF в PDF/A — формат долговременного хранения для архивов, судов и госорганов. Документ с электронной подписью не конвертируется: подпись перестала бы действовать.
- [Восстановить PDF](https://smartpdf.ru/developers/docs/operations/repair.md): /v1/pdf/repair — Восстанавливает повреждённый PDF, который не открывается или открывается с ошибкой. Если восстановить нечего — ошибка без списания.
- [Обрезать PDF](https://smartpdf.ru/developers/docs/operations/crop.md): /v1/pdf/crop — Обрезает страницы PDF по рамке или убирает белые поля автоматически. Содержимое за краем остаётся в файле — чтобы скрыть данные, используйте redact.
- [Скрыть персональные данные](https://smartpdf.ru/developers/docs/operations/redact.md): /v1/pdf/redact — Скрывает персональные данные: находит их сама (find) и/или берёт области (areas) и удаляет из файла — под чёрными прямоугольниками текста и пикселей больше нет. Ничего не нашлось и областей нет — ошибка без списания.
- [Найти персональные данные](https://smartpdf.ru/developers/docs/operations/find-personal-data.md): /v1/pdf/find-personal-data — Находит персональные данные в PDF, файл не меняет. Результат — JSON: {"pages": [{"page", "items": [{"kind", "text", "boxes"}]}], "scanned": [страницы-сканы без текста], "total"}; boxes — [x0, y0, x1, y1] долями страницы, их можно передать в redact как areas.

## MCP и агенты

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

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

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

## Optional

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