La mateixa operació, quatre clients: navegador, curl, MCP i pdfx
La mateixa unió de PDF123 des de quatre clients: el formulari del navegador, curl a /api/v1/general/merge-pdfs, MCP a /mcp i pdfx local o al núvol.
Quatre clients semblen quatre productes. Comparteixen un sol catàleg. Agafeu Uneix com a tasca concreta: combinar PDF en l'ordre de càrrega sense rasteritzar les pàgines en imatges. El mateix patró val per a qualsevol altra eina del catàleg (comprimir, OCR, convertir i la resta): un sol identificador d'operació i quatre maneres de cridar-la.
Navegador
Obriu /merge, afegiu fitxers en l'ordre que vulgueu, premeu Processa i baixeu el resultat. Les eines del catàleg no demanen compte. El bloc «Crida-ho des del codi» de la pàgina construeix un curl amb els mateixos camps que envia el formulari, de manera que la interfície i el contracte HTTP es mantenen alineats.
Aquest bloc no és text de màrqueting. Es genera a partir de la definició de l'eina que el portal ja fa servir per al formulari, i per això un canvi de nom d'un paràmetre apareix als dos llocs alhora. Si el formulari accepta sortType=byFileName opcional, l'exemple de curl també pot portar el mateix camp.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
Les crides anònimes del catàleg no necessiten cap clau. Les claus de Desenvolupadors donen a l'automatització una identitat estable (i als servidors autoallotjats, una porta). L'OpenAPI és a /v1/openapi.json.
Per a les tasques de diversos passos, POST /api/v1/pipeline accepta operacions ordenades en un camp steps (per exemple unir, després marcar amb aigua i després comprimir). Envieu Idempotency-Key quan els reintents no hagin de duplicar la feina; una repetició correcta pot tornar amb Idempotency-Replayed. Els errors fan servir application/problem+json amb codis estables com rate_limited i bad_request (Errors per a desenvolupadors).
Les respostes allotjades també anuncien X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset; l'HTTP 429 inclou Retry-After. Tracteu aquestes capçaleres com el pressupost viu, no com un número memoritzat d'un article (limitació de taxa anònima).
MCP
Els agents que parlen Model Context Protocol es connecten a /mcp, descobreixen l'operació d'unir com una eina i la criden amb la mateixa història de claus d'API que el REST. Documentació: MCP per a desenvolupadors.
L'MCP no és un segon catàleg. És un protocol de descobriment i invocació sobre les mateixes operacions que llista l'OpenAPI. Si una operació falta a l'MCP, és un error del servidor, no una línia de producte a part. Combineu l'MCP amb /llms.txt quan vulgueu un índex en prosa de les eines abans que el client es connecti.
La CLI pdfx
pdf-core local:
pdfx merge a.pdf b.pdf -o merged.pdf
O el mateix servidor que fa servir el portal:
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
El mode local no carrega mai res; el mode núvol ataca la vostra URL base amb la mateixa forma multipart que curl. L'habilitat per a agents de programació que hi ha a dist/skills/pdf-toolbox/SKILL.md documenta les mateixes formes d'unió i de pipeline perquè els agents no s'inventin un segon OpenAPI.
L'OCR a través de qualsevol d'aquests clients continua retornant Markdown des de /api/v1/misc/ocr-pdf, no una capa de text oculta. Aquest fet forma part del contracte compartit: canviar el tipus de retorn en un client sense fer-ho als altres trencaria la promesa de «la mateixa operació». La compressió es manté a /api/v1/misc/compress-pdf per a la recompressió de fluxos; és una operació diferent de la unió, però s'hi arriba de les mateixes quatre maneres.
Per què importa aquesta igualtat
Si la unió del navegador i la unió de l'API divergissin, les automatitzacions regredirien en silenci mentre la pàgina de demostració encara semblaria correcta. Una operació i quatre camins és precisament l'objectiu. El portal és un client de conveniència, no una segona implementació d'unir, comprimir o fer OCR.
Per això tampoc no hi ha una bifurcació d'escriptori: un cinquè arbre d'interfície recrearia el problema de la divergència sota un altre nom de binari. Per al context més ampli, vegeu Fet per a agents d'IA, no només navegadors. Sobre la decisió d'escriptori, vegeu Per què vam descartar l'aplicació d'escriptori. Per alçar l'API a la vostra xarxa, vegeu Autoallotjament.