La stessa operazione, quattro client: browser, curl, MCP, pdfx
Lo stesso merge di PDF123 da quattro client: il modulo browser, curl su /api/v1/general/merge-pdfs, MCP su /mcp e pdfx locale o --cloud sulla tua base API.
Quattro client sembrano quattro prodotti. In realtà condividono un unico catalogo. Prendi Unisci come operazione concreta: combina PDF nell'ordine di caricamento senza rasterizzare le pagine in immagini. Lo stesso schema vale per ogni altro strumento del catalogo (comprimi, OCR, converti e gli altri): un id di operazione, quattro modi di chiamarla.
Browser
Apri /merge, aggiungi i file nell'ordine che vuoi, clicca Process, scarica. Nessun account per gli strumenti del catalogo. Il blocco «Call this from code» della pagina costruisce il curl dagli stessi campi che invia il modulo, così l'interfaccia e il contratto HTTP restano allineati.
Quel blocco non è testo di marketing. È generato dalla definizione dello strumento che il portale già usa per il modulo, ed è per questo che la rinomina di un parametro compare in entrambi i posti contemporaneamente. Se il modulo accetta l'opzione sortType=byFileName, l'esempio curl può riportare lo stesso campo.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
Le chiamate anonime al catalogo non richiedono chiave. Le chiavi di Developers danno all'automazione un'identità stabile (e ai server self-hosted un controllo d'accesso). OpenAPI è su /v1/openapi.json.
Per le attività in più passaggi, POST /api/v1/pipeline accetta operazioni ordinate in un campo steps (per esempio unire, poi applicare una filigrana, poi comprimere). Invia Idempotency-Key quando i nuovi tentativi non devono rieseguire il lavoro; una ripetizione andata a buon fine può tornare con Idempotency-Replayed. I fallimenti usano application/problem+json con codici stabili come rate_limited e bad_request (Developers errors).
Le risposte ospitate espongono anche X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; HTTP 429 include Retry-After. Considera quelle intestazioni come il budget reale, non come un numero memorizzato da un articolo del blog (limite di frequenza anonimo).
MCP
Gli agenti che parlano Model Context Protocol si collegano a /mcp, scoprono merge come strumento e lo chiamano con la stessa logica delle API key di REST. Documentazione: Developers MCP.
MCP non è un secondo catalogo. È un protocollo di scoperta e invocazione sulle stesse operazioni elencate da OpenAPI. Se un'operazione manca in MCP, è un bug del server, non una roadmap di prodotto separata. Abbina MCP a /llms.txt quando vuoi un indice in prosa degli strumenti prima che il client si colleghi.
CLI pdfx
pdf-core in locale:
pdfx merge a.pdf b.pdf -o merged.pdf
Oppure lo stesso server usato dal portale:
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
La modalità locale non carica mai nulla; quella cloud raggiunge il tuo URL di base con la stessa forma multipart di curl. La skill per gli agenti di programmazione in dist/skills/pdf-toolbox/SKILL.md documenta le stesse forme di merge e pipeline, così gli agenti non inventano un secondo OpenAPI.
L'OCR attraverso uno di questi client restituisce comunque Markdown da /api/v1/misc/ocr-pdf, non uno strato di testo nascosto. Questo fatto fa parte del contratto condiviso: cambiare il tipo di ritorno in un client senza gli altri romperebbe la promessa della «stessa operazione». Comprimi resta su /api/v1/misc/compress-pdf per la ricompressione degli stream; è un'operazione diversa dal merge, raggiungibile negli stessi quattro modi.
Perché l'identità conta
Se il merge nel browser e il merge via API divergessero, le automazioni peggiorerebbero in silenzio mentre la pagina demo sembrerebbe ancora a posto. Un'operazione, quattro modi di chiamarla: è questo il punto. Il portale è un client comodo, non una seconda implementazione di merge, compress o OCR.
È anche il motivo per cui non esiste un fork desktop: un quinto albero di interfacce ricreerebbe il problema della divergenza sotto un altro nome di binario. Per il quadro più ampio: Costruito per gli agenti AI, non solo per il browser. Sulla decisione relativa al desktop, vedi Perché abbiamo evitato l'app desktop. Per mettere in piedi l'API sulla tua rete, vedi Self-host.