Одна операция, четыре клиента: браузер, curl, MCP, pdfx
Одно и то же слияние PDF123 через четыре клиента: форма в браузере, curl на /api/v1/general/merge-pdfs, MCP на /mcp и pdfx локально или с --cloud против вашего API.
Четыре клиента выглядят как четыре продукта. Они делят один каталог. Возьмём Merge как конкретную задачу: объединить PDF в порядке загрузки, не растеризуя страницы в изображения. Та же схема верна для любого другого инструмента каталога (сжатие, OCR, конвертация и остальные): один идентификатор операции, четыре способа её вызвать.
Браузер
Откройте /merge, добавьте файлы в нужном порядке, нажмите Process, скачайте. Для инструментов каталога аккаунт не нужен. Блок «Call this from code» на странице собирает curl из тех же полей, которые отправляет форма, поэтому интерфейс и HTTP-контракт остаются согласованными.
Этот блок — не рекламный текст. Он генерируется из определения инструмента, которое портал уже использует для формы; поэтому переименование параметра появляется в обоих местах одновременно. Если форма принимает необязательный sortType=byFileName, пример curl может нести то же поле.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
Анонимные вызовы каталога не требуют ключа. Ключи из раздела Разработчикам дают автоматизации стабильную идентичность (а собственным серверам — гейт). OpenAPI лежит на /v1/openapi.json.
Для многошаговых задач POST /api/v1/pipeline принимает упорядоченные операции в поле steps (например, слияние, затем водяной знак, затем сжатие). Отправляйте Idempotency-Key, когда повторные попытки не должны запускать работу дважды; успешный повтор может вернуться с Idempotency-Replayed. Сбои используют application/problem+json со стабильными кодами вроде rate_limited и bad_request (Ошибки для разработчиков).
Ответы хостинга также сообщают X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset; HTTP 429 включает Retry-After. Считайте эти заголовки живым бюджетом, а не числом, заученным из поста в блоге (анонимное ограничение частоты).
MCP
Агенты, говорящие на Model Context Protocol, подключаются к /mcp, обнаруживают merge как инструмент и вызывают его с той же историей API-ключа, что и REST. Документация: MCP для разработчиков.
MCP — не второй каталог. Это протокол обнаружения и вызова поверх тех же операций, которые перечисляет OpenAPI. Если операции нет в MCP, это баг сервера, а не отдельная дорожная карта продукта. Сочетайте MCP с /llms.txt, когда хотите прозаический индекс инструментов до подключения клиента.
CLI pdfx
Локальный pdf-core:
pdfx merge a.pdf b.pdf -o merged.pdf
Или тот же сервер, которым пользуется портал:
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
Локальный режим никогда не загружает; облачный режим обращается к вашему базовому URL с той же multipart-формой, что и curl. Skill для агентов-программистов в dist/skills/pdf-toolbox/SKILL.md документирует те же формы merge и pipeline, чтобы агенты не изобретали второй OpenAPI.
OCR через любого из этих клиентов по-прежнему возвращает Markdown из /api/v1/misc/ocr-pdf, а не скрытый текстовый слой. Этот факт — часть общего контракта: изменение типа возврата в одном клиенте без остальных сломало бы обещание «одной операции». Compress остаётся на /api/v1/misc/compress-pdf для пережатия потоков; это другая операция, нежели merge, и доступна теми же четырьмя способами.
Почему тождество важно
Если бы слияние в браузере и слияние через API когда-нибудь разошлись, автоматизации молча деградировали бы, пока демонстрационная страница всё ещё выглядела бы нормально. Одна операция, четыре способа — в этом суть. Портал — удобный клиент, а не вторая реализация merge, compress или OCR.
Именно поэтому нет ответвления под настольную версию: пятое дерево интерфейса воссоздало бы проблему расхождения под другим именем бинарника. Более широкая рамка: Создан для AI-агентов, а не только для браузеров. О решении по настольной версии см. Почему мы отказались от настольного приложения. О подъёме API в вашей сети см. Self-host.