Samma operation, fyra klienter: webbläsare, curl, MCP, pdfx

Fyra klienter ser ut som fyra produkter, men de delar en och samma katalog. Ta Slå ihop PDF som konkret exempel: kombinera PDF:er i uppladdningsordning utan att rastrera sidorna till bilder. Samma mönster gäller varje annat katalogverktyg (komprimera, OCR, konvertera och resten): ett operations-id, fyra sätt att anropa det.

Webbläsaren

Öppna /merge, lägg till filerna i den ordning du vill ha dem, kör och ladda ner. Katalogverktygen kräver inget konto. Sidans block ”Anropa från kod” bygger ett curl-kommando från samma fält som formuläret skickar, så gränssnittet och HTTP-kontraktet hålls i linje.

Det blocket är inte marknadsföringstext. Det genereras från samma verktygsdefinition som portalen redan använder för formuläret, och därför syns ett namnbyte på en parameter på båda ställena samtidigt. Tar formuläret emot det valfria fältet sortType=byFileName kan curl-exemplet bära samma fält.

curl / REST

curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o merged.pdf

Anonyma kataloganrop kräver ingen nyckel. Nycklar från Utvecklare ger automatiseringen en stabil identitet (och självhostade servrar en spärr). OpenAPI ligger på /v1/openapi.json.

För jobb i flera steg tar POST /api/v1/pipeline emot ordnade operationer i ett steps-fält (till exempel slå ihop, vattenstämpla, komprimera). Skicka Idempotency-Key när återförsök inte får köra arbetet två gånger; en lyckad uppspelning kan komma tillbaka med Idempotency-Replayed. Fel använder application/problem+json med stabila koder som rate_limited och bad_request (Fel i utvecklar-API:t).

Svar från den hostade tjänsten annonserar också X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset; HTTP 429 innehåller Retry-After. Behandla de huvudena som den aktuella budgeten, inte som ett tal du memorerat från en bloggtext (anonym hastighetsbegränsning).

MCP

Agenter som talar Model Context Protocol ansluter till /mcp, hittar sammanslagningen som ett verktyg och anropar det med samma nyckelmodell som REST. Dokumentation: MCP för utvecklare.

MCP är inte en andra katalog. Det är ett protokoll för upptäckt och anrop ovanpå samma operationer som OpenAPI listar. Saknas en operation i MCP är det en bugg i servern, inte en separat produktplan. Para ihop MCP med /llms.txt när du vill ha ett index i prosaform över verktygen innan klienten ansluter.

Kommandoradsverktyget pdfx

Lokal pdf-core:

pdfx merge a.pdf b.pdf -o merged.pdf

Eller samma server som portalen använder:

pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf

Det lokala läget laddar aldrig upp något; molnläget träffar din basadress med samma multipart-form som curl. Agent-skillen under dist/skills/pdf-toolbox/SKILL.md dokumenterar samma former för sammanslagning och pipeline, så att agenter inte hittar på ett andra OpenAPI.

OCR via vilken som helst av klienterna returnerar fortfarande Markdown från /api/v1/misc/ocr-pdf, inte ett dolt textlager. Det är en del av det delade kontraktet: att ändra returtypen i en klient utan att ändra de andra skulle bryta löftet om ”samma operation”. Komprimering ligger kvar på /api/v1/misc/compress-pdf för omkomprimering av strömmar; det är en annan operation än sammanslagning, men nåbar på samma fyra sätt.

Varför likheten spelar roll

Om sammanslagning i webbläsaren och via API:et någonsin gled isär skulle automatiseringarna tyst sluta fungera medan demosidan fortfarande såg bra ut. En operation, fyra sätt att nå den, är själva poängen. Portalen är en bekvämlighetsklient, inte en andra implementation av sammanslagning, komprimering eller OCR.

Det är också därför det inte finns någon skrivbordsvariant: ett femte gränssnittsträd skulle återskapa samma driftproblem under ett annat filnamn. En bredare inramning finns i Byggd för AI-agenter, inte bara webbläsare. Om skrivbordsbeslutet, se Varför vi avstod från skrivbordsappen. För att resa API:et i ditt eget nätverk, se Kör själv.