Една и съща операция, четири клиента: браузър, curl, MCP, pdfx

Четири клиента изглеждат като четири продукта. Те споделят един каталог. Вземете Merge като конкретна задача: комбинира PDF в реда на качване, без да превръща страниците в изображения. Същият модел важи за всеки друг инструмент от каталога (compress, OCR, convert и останалите): един идентификатор на операцията, четири начина да я извикате.

Браузър

Отворете /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

Анонимните заявки към каталога не изискват ключ. Ключовете от Developers дават на автоматизацията стабилна самоличност (и защита за самостоятелно хостваните сървъри). 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, когато искате текстов индекс на инструментите, преди клиентът да се свърже.

pdfx CLI

Локален 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. Skill-ът за агент за програмиране в dist/skills/pdf-toolbox/SKILL.md документира същите форми за merge и pipeline, за да не си измислят агентите втори OpenAPI.

OCR през всеки от тези клиенти пак връща Markdown от /api/v1/misc/ocr-pdf, а не скрит текстов слой. Този факт е част от споделения договор: промяна на типа на връщане в един клиент, без останалите, би нарушила обещанието за „същата операция“. Compress остава на /api/v1/misc/compress-pdf за прекомпресия на потоци; това е различна операция от сливането, достъпна по същите четири начина.

Защо еднаквостта има значение

Ако сливането в браузъра и сливането през API се разминаеха, автоматизациите тихо щяха да се влошават, докато демонстрационната страница още изглежда добре. Една операция, четири начина за достъп: това е смисълът. Порталът е удобен клиент, а не втора реализация на merge, compress или OCR.

Затова няма и настолен вариант: пето дърво от интерфейси би пресъздало проблема с разминаването под друго име на изпълним файл. По-широката рамка: Създаден за AI агенти, не само за браузъри. За решението относно настолното приложение вижте Защо пропуснахме настолното приложение. За вдигане на API във вашата мрежа вижте Self-host.