같은 연산, 네 가지 클라이언트: 브라우저, curl, MCP, pdfx
같은 PDF123 병합을 네 가지 클라이언트로 부릅니다. 브라우저 폼, REST로 가는 curl, /mcp의 MCP, 로컬이나 --cloud의 pdfx이며 하나의 op와 한 계약을 공유합니다.
네 가지 클라이언트는 네 개의 제품처럼 보입니다. 하지만 하나의 카탈로그를 공유합니다. 구체적인 작업으로 PDF 병합을 보면, 페이지를 이미지로 래스터화하지 않고 업로드 순서대로 PDF를 합칩니다. 다른 카탈로그 도구(압축, OCR, 변환 등)도 같은 패턴입니다. 하나의 op id, 네 가지 호출 방식입니다.
브라우저
/merge를 열고, 원하는 순서로 파일을 추가하고, Process를 누르고, 내려받습니다. 카탈로그 도구에는 계정이 필요 없습니다. 페이지의 “Call this from code” 블록은 폼이 보내는 것과 같은 필드로 curl을 만들므로 UI와 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 필드에 순서 있는 op를 받습니다(예: 병합, 그다음 워터마크, 그다음 압축). 재시도가 같은 작업을 두 번 돌리면 안 될 때 Idempotency-Key를 보내세요. 성공한 재생은 Idempotency-Replayed와 함께 돌아올 수 있습니다. 실패는 rate_limited, bad_request 같은 안정적인 코드를 담은 application/problem+json입니다(개발자 오류).
호스팅 응답은 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset도 알립니다. HTTP 429에는 Retry-After가 들어 있습니다. 이 헤더를 블로그 글에서 외운 숫자가 아니라 실시간 예산으로 대하세요(익명 요청 제한).
MCP
Model Context Protocol을 쓰는 에이전트는 /mcp에 연결해 병합을 도구로 발견하고, REST와 같은 API 키 규칙으로 호출합니다. 문서: 개발자 MCP.
MCP는 두 번째 카탈로그가 아닙니다. OpenAPI가 나열하는 같은 연산 위에 얹힌 발견과 호출 프로토콜입니다. 어떤 op가 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
로컬 모드는 업로드하지 않습니다. 클라우드 모드는 curl과 같은 multipart 형태로 내 base URL을 칩니다. dist/skills/pdf-toolbox/SKILL.md 아래의 coding-agent skill이 같은 merge와 pipeline 형태를 문서화해, 에이전트가 두 번째 OpenAPI를 만들어 내지 않게 합니다.
이 클라이언트 중 어느 것으로 OCR을 하든 /api/v1/misc/ocr-pdf에서 Markdown을 반환하며 숨은 텍스트 레이어가 아닙니다. 이 사실은 공유 계약의 일부입니다. 한 클라이언트만 반환 타입을 바꾸면 “같은 op”라는 약속이 깨집니다. 압축은 스트림 재압축을 위해 /api/v1/misc/compress-pdf에 남아 있고, 병합과는 다른 op이면서 같은 네 가지 방식으로 닿습니다.
동일함이 중요한 이유
브라우저 병합과 API 병합이 갈라지면, 데모 페이지는 멀쩡해 보여도 자동화가 조용히 퇴행합니다. 하나의 op, 네 개의 손잡이가 핵심입니다. 포털은 편의 클라이언트이지 병합이나 압축, OCR의 두 번째 구현이 아닙니다.
데스크톱 포크가 없는 이유도 같습니다. 다섯 번째 UI 트리는 다른 바이너리 이름으로 같은 드리프트 문제를 다시 만듭니다. 더 넓은 맥락은 AI 에이전트를 위해 만들어진 API를 보세요. 데스크톱 결정은 데스크톱 앱을 만들지 않은 이유를 보세요. 내 네트워크에 API를 세우려면 자체 호스팅을 보세요.