Ta sama operacja, cztery klienty: przeglądarka, curl, MCP, pdfx
Ten sam merge w PDF123 przez cztery klienty: formularz przeglądarki, curl na /api/v1/general/merge-pdfs, MCP pod /mcp oraz pdfx lokalnie lub w chmurze.
Cztery klienty wyglądają jak cztery produkty. Dzielą jeden katalog. Weź Scal PDF jako konkretne zadanie: połącz pliki w kolejności przesyłania, bez rasteryzowania stron do obrazów. Ten sam wzorzec działa dla każdego innego narzędzia z katalogu (kompresja, OCR, konwersja i reszta): jeden identyfikator operacji, cztery sposoby jej wywołania.
Przeglądarka
Otwórz /merge, dodaj pliki w żądanej kolejności, kliknij „Przetwórz”, pobierz wynik. Narzędzia z katalogu nie wymagają konta. Blok „Call this from code” na stronie narzędzia buduje curl z tych samych pól, które wysyła formularz, więc interfejs i kontrakt HTTP pozostają zgodne.
Ten blok to nie tekst marketingowy. Powstaje z definicji narzędzia, której portal używa już do formularza, dlatego zmiana nazwy parametru pojawia się w obu miejscach jednocześnie. Jeśli formularz przyjmuje opcjonalny sortType=byFileName, przykład curl również może nieść to samo pole.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
Anonimowe wywołania katalogu nie wymagają klucza. Klucze ze strony Dla programistów dają automatyzacji stabilną tożsamość (a serwerom self-hosted bramkę). OpenAPI jest pod /v1/openapi.json.
W zadaniach wieloetapowych POST /api/v1/pipeline przyjmuje uporządkowane operacje w polu steps (na przykład scalenie, potem znak wodny, potem kompresja). Dodaj Idempotency-Key, gdy ponowienie nie może wykonać pracy dwa razy; udane powtórzenie może wrócić z Idempotency-Replayed. Błędy używają application/problem+json ze stabilnymi kodami, takimi jak rate_limited i bad_request (Błędy dla programistów).
Odpowiedzi hostowane podają też X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset; przy HTTP 429 dochodzi Retry-After. Traktuj te nagłówki jako bieżący budżet, a nie liczbę zapamiętaną z artykułu (anonimowe limity tempa).
MCP
Agenci, którzy rozumieją Model Context Protocol, łączą się z /mcp, odkrywają scalanie jako narzędzie i wywołują je z tą samą historią klucza API co REST. Dokumentacja: MCP dla programistów.
MCP to nie drugi katalog. To protokół odkrywania i wywoływania tych samych operacji, które wymienia OpenAPI. Jeśli jakiejś operacji brakuje w MCP, to błąd serwera, a nie odrębny plan produktu. Połącz MCP z /llms.txt, gdy chcesz mieć tekstowy indeks narzędzi przed połączeniem klienta.
pdfx CLI
Lokalnie, przez pdf-core:
pdfx merge a.pdf b.pdf -o merged.pdf
Albo przeciwko temu samemu serwerowi, którego używa portal:
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
Tryb lokalny nigdy nie przesyła plików; tryb chmurowy uderza w twój adres bazowy z tym samym kształtem multipart co curl. Skill dla agenta kodującego w dist/skills/pdf-toolbox/SKILL.md opisuje te same kształty scalania i potoku, aby agenci nie wymyślali drugiego OpenAPI.
OCR przez któregokolwiek z tych klientów nadal zwraca Markdown ze ścieżki /api/v1/misc/ocr-pdf, a nie ukrytą warstwę tekstu. To fakt należący do wspólnego kontraktu: zmiana typu zwracanego w jednym kliencie bez pozostałych łamie obietnicę „tej samej operacji”. Compress pozostaje pod /api/v1/misc/compress-pdf i odpowiada za ponowną kompresję strumieni; to inna operacja niż scalanie, osiągalna tymi samymi czterema drogami.
Dlaczego identyczność ma znaczenie
Gdyby scalanie w przeglądarce i scalanie przez API kiedykolwiek się rozjechały, automatyzacje psułyby się po cichu, a strona demonstracyjna nadal wyglądałaby dobrze. Jedna operacja, cztery drogi dostępu, o to chodzi. Portal jest wygodnym klientem, a nie drugą implementacją scalania, kompresji czy OCR.
To także powód, dla którego nie ma forka desktopowego: piąte drzewo interfejsu odtworzyłoby problem rozjazdu pod inną nazwą pliku. Szersze ujęcie: Stworzone z myślą o agentach AI, nie tylko o przeglądarkach. Decyzję o wersji desktopowej opisuje Dlaczego pominęliśmy aplikację desktopową. Postawienie API w swojej sieci: Self-host.