Та сама операція, чотири клієнти: браузер, curl, MCP, pdfx
Той самий merge у PDF123 через чотири клієнти: форму браузера, curl, MCP на /mcp і pdfx локально чи --cloud проти вашої базової адреси API.
Чотири клієнти виглядають як чотири продукти. Насправді вони поділяють один каталог. Візьмімо Об’єднання як конкретну задачу: поєднати PDF у порядку завантаження, не растеризуючи сторінки в зображення. Той самий шаблон діє й для кожного іншого інструменту каталогу (стиснення, OCR, конвертація та решта): один ідентифікатор операції, чотири способи її викликати.
Браузер
Відкрийте /merge, додайте файли в потрібному порядку, натисніть «Обробити», звантажте. Для інструментів каталогу обліковий запис не потрібен. Блок із прикладом виклику з коду на сторінці будує 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, знаходять об’єднання як інструмент і викликають його з тією самою історією ключів 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
Локальний режим ніколи не завантажує файли; хмарний режим звертається до вашої базової адреси з тією самою формою multipart, що й curl. Навичка для агентів-програмістів у dist/skills/pdf-toolbox/SKILL.md описує ті самі форми об’єднання й конвеєра, щоб агенти не вигадували другого OpenAPI.
OCR через будь-який із цих клієнтів і далі повертає Markdown з /api/v1/misc/ocr-pdf, а не прихований текстовий шар. Цей факт — частина спільного контракту: змінити тип повернення в одному клієнті без інших означало б зламати обіцянку «тієї самої операції». Стиснення лишається на /api/v1/misc/compress-pdf для перестиснення потоків; це інша операція, ніж об’єднання, доступна тими самими чотирма способами.
Чому однаковість важлива
Якби об’єднання в браузері й об’єднання через API колись розійшлися, автоматизації нишком регресували б, тоді як демонстраційна сторінка виглядала б добре. Одна операція, чотири способи — у цьому суть. Портал — це зручний клієнт, а не друга реалізація об’єднання, стиснення чи OCR.
Тому ж немає й настільного форку: п’яте дерево інтерфейсу відтворило б проблему розходження під іншою назвою бінарника. Ширший контекст: Зроблено для AI-агентів, а не лише для браузерів. Про рішення щодо настільного застосунку див. Чому ми відмовилися від настільного застосунку. Про підняття API у вашій мережі див. Власний хостинг.