Przejdź do głównej treści
PPDF123

PDF123 dla deweloperów: API REST, SDK, wiersz poleceń i MCP

Platforma deweloperska PDF123 udostępnia te same 97 narzędzi PDF przez cztery interfejsy: API REST opisane w OpenAPI, SDK TypeScript, wiersz poleceń pdfx i serwery MCP dla agentów AI. Wywołania anonimowe nie wymagają konta ani klucza API.

Na tej stronie

Jak korzystać z PDF123 w kodzie?

Wszystkie cztery interfejsy wywołują te same operacje, więc połączenie plików daje w każdym z nich ten sam wynik. Wybierz ten, który pasuje do miejsca, w którym działa Twój kod.

InterfejsNajlepszy doInstalacja lub adresPrzewodnik
API RESTDowolnego języka, serwerów, skryptów powłokihttps://pdf123.xyz/api/v1Dokumentacja API
SDK TypeScriptKodu Node, Bun i przeglądarki, który potrzebuje typównpm install @pdf123/sdkPrzewodnik po SDK
Wiersz poleceńTerminali, zadań CI, partii plików lokalnychnpm install -g @pdf123/cliPrzewodnik po CLI
MCPAgentów AI, takich jak Claude Code, Claude Desktop i Cursornpx -y @pdf123/mcp lub https://pdf123.xyz/mcpPrzewodnik po MCP

Jeśli Twój kod nie jest napisany w TypeScripcie, użyj API REST. Jeśli jest, użyj SDK, bo opcje narzędzi są typowane i sprawdzane przed wysłaniem. Do jednorazowych zadań i skryptów powłoki użyj wiersza poleceń. MCP wybierz wtedy, gdy to agent AI ma zdecydować, które narzędzie uruchomić.

Katalog zawiera 97 narzędzi. 58 z nich ma stronę w tym serwisie, na przykład Połącz PDF, Podziel PDF i Kompresuj PDF. Pozostałe to operacje backendu bez strony internetowej, a wszystkie są dostępne w SDK, wierszu poleceń i MCP.

Jak wysłać pierwsze żądanie?

Połącz dwa pliki za pomocą curl. Żądanie to formularz multipart z jedną częścią fileInput na każdy plik.

REST: połączenie dwóch plików PDFbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

To samo połączenie w SDK TypeScript:

SDK: połączenie dwóch plików PDFts
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const result = await client.run("merge", {
  input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
await saveResult(result, { output: "merged.pdf" });

To samo połączenie w wierszu poleceń:

CLI: połączenie dwóch plików PDFbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Jak działa uwierzytelnianie?

Anonimowe wywołania publicznego API nie wymagają konta ani klucza. Klucz API wyślij w nagłówku X-API-KEY, gdy chcesz oznaczyć swój ruch lub wywołać hostowany endpoint MCP, który zawsze wymaga klucza.

Zaloguj się, aby utworzyć klucz w panelu poniżej, i przechowuj go w bezpiecznym miejscu.

Sprawdzanie sesji…

Wywołanie API z kluczembash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -H "X-API-KEY: <your-key>" \
  -F [email protected] -F [email protected] -o merged.pdf

SDK przyjmuje klucz jako apiKey. Wiersz poleceń i lokalny serwer MCP odczytują go ze zmiennej środowiskowej PDFX_API_KEY.

Uwaga

Na samodzielnie hostowanym serwerze ustaw zmienną środowiskową SECURITY_CUSTOMGLOBALAPIKEY, aby zdefiniować jeden klucz akceptowany przez serwer. Zobacz Self-host.

Gdzie jest dokumentacja API?

API REST jest udokumentowane w dwóch postaciach. Swagger UI pozwala wypróbować każdy endpoint w przeglądarce. Dokument OpenAPI to źródło czytelne maszynowo, przeznaczone dla generatorów klientów.

Każda operacja to POST pod adresem bazowym https://pdf123.xyz/api/v1, pogrupowany według kategorii. Na przykład łączenie to /general/merge-pdfs, a kompresja to /misc/compress-pdf.

Jak połączyć kilka narzędzi w jednym żądaniu?

POST /api/v1/pipeline przyjmuje części fileInput oraz pole steps. Pole steps to tablica JSON obiektów z op i opcjonalnym params. Każdy krok otrzymuje wynik poprzedniego kroku.

Połączenie, a potem kompresja w jednym żądaniubash
curl -X POST https://pdf123.xyz/api/v1/pipeline \
  -F [email protected] -F [email protected] \
  -F 'steps=[{"op":"general/merge-pdfs"},{"op":"misc/compress-pdf"}]' \
  -o out.pdf

Jak bezpiecznie ponowić żądanie?

Wyślij nagłówek Idempotency-Key przy dowolnej operacji. Powtórzenie tego samego żądania w ciągu 24 godzin zwraca pierwszy wynik z nagłówkiem Idempotency-Replayed: true zamiast uruchamiać operację ponownie. Użycie tego samego klucza dla innego żądania jest odrzucane. Wyniki większe niż 32 MiB nie są zapisywane, więc powtórzenie takiego żądania kończy się odpowiedzią 409 i wymaga nowego klucza.

Jakie są limity rozmiaru i liczby żądań?

LimitWartość
Rozmiar pliku w serwisie500 MB na plik
Jedno bezpośrednie żądanie API100 MiB, łącznie z ramkowaniem multipart
Przesyłanie we fragmentachSDK przełącza się automatycznie na API przesyłania, gdy łączny rozmiar przekracza 95 MB

Odpowiedzi zawierają nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odpowiedź ze statusem 429 dodaje Retry-After. Czytaj nagłówki zamiast zakładać stały limit, ponieważ samodzielnie hostowany serwer ustala własne limity. Wpis na blogu o limicie rozmiaru żądania wyjaśnia błąd, który dostaniesz przy zbyt dużym ciele żądania.

Jak wygląda błąd?

Błędy zwracają application/problem+json z polami type, title, status, detail, code, reason i hint. Rozgałęziaj logikę według reason, a w razie braku użyj code. Tekst detail jest pisany dla ludzi i nigdy nie zawiera surowego wyniku narzędzia. Wszystkie kody znajdziesz na stronie Kody błędów.

Kod lub przyczynaStatus HTTPZnaczenie
bad_request400Nieprawidłowe parametry lub treść multipart
password_required400PDF jest zaszyfrowany, a hasło nie zostało wysłane
invalid_pdf400Plik nie jest PDF-em lub jest uszkodzony; spróbuj Napraw PDF
page_out_of_range400Żądana strona nie istnieje
not_found404Nieznana ścieżka operacji
rate_limited429Limit wykorzystany; poczekaj zgodnie z Retry-After

Które narzędzia wywołać na początek?

Tych dwanaście narzędzi obejmuje większość żądań. Na stronie narzędzia możesz je wypróbować w przeglądarce.

Strona narzędziaEndpoint APIPolecenie CLICo robi
Połącz/general/merge-pdfspdfx mergeŁączy kilka plików PDF w jeden
Podziel/general/split-pagespdfx splitDzieli PDF na osobne pliki
Kompresuj/misc/compress-pdfpdfx compressKompresuje strumienie PDF ponownie, aby zmniejszyć rozmiar
Obróć/general/rotate-pdfpdfx rotateZmienia orientację stron
Zabezpiecz/security/add-passwordpdfx protectSzyfruje PDF hasłem
Odblokuj/security/remove-passwordpdfx unlockUsuwa ochronę hasłem
Znak wodny/security/add-watermarkpdfx watermarkDodaje znak wodny z tekstu lub obrazu
OCR/misc/ocr-pdfpdfx ocrOdczytuje zeskanowany PDF i zwraca Markdown
PDF do Markdown/convert/pdf/markdownpdfx pdf-to-markdownKonwertuje PDF na Markdown
PDF do Worda/convert/pdf/wordpdfx convert-to-wordKonwertuje PDF na edytowalny plik Word
Informacje o dokumencie/security/get-info-on-pdfpdfx get-infoPodaje metadane, uprawnienia, czcionki i strukturę
Napraw/misc/repairpdfx repairOdbudowuje strukturę uszkodzonego PDF-a

Endpointy są podane względem https://pdf123.xyz/api/v1. Uruchom pdfx list lub otwórz dokument OpenAPI, aby zobaczyć wszystkie 97 narzędzi.

Jak używać PDF123 z agenta AI?

Agent może korzystać z narzędzi na trzy sposoby:

  • Podłącz serwer MCP. Przewodnik po MCP opisuje lokalny serwer @pdf123/mcp dla plików na Twoim komputerze oraz hostowany endpoint pod adresem https://pdf123.xyz/mcp.
  • Załaduj skill agenta. Skille dla agentów to pliki SKILL.md dla Claude Code, Codex, Cursor i podobnych narzędzi: jeden dla katalogu i po jednym dla każdego narzędzia.
  • Przeczytaj indeks serwisu. /llms.txt wymienia narzędzia, API i endpoint MCP zwykłym tekstem, a /site.jsonld opisuje serwis jako dane strukturalne.

Wpis „Built for AI Agents, Not Just Browsers” na blogu PDF123 wyjaśnia, jak API REST i MCP łączą się ze sobą.

Czy mogę uruchomić PDF123 na własnym serwerze?

Tak. Backend to program pdfx-server, który działa w Dockerze. Skieruj na niego SDK, wiersz poleceń lub serwer MCP za pomocą PDFX_API_BASE, a Twoje pliki zostaną w Twojej sieci. Instrukcję konfiguracji znajdziesz w Self-host, a opcje wsparcia na stronie Enterprise.

FAQ

Czy API PDF123 jest bezpłatne?

Tak, przy użyciu anonimowym. Wywołania publicznego API nie wymagają konta ani klucza. Odpowiedzi z hostowanego API zawierają nagłówki limitów, dzięki czemu klient może zwolnić, zanim dostanie odpowiedź 429.

Czy potrzebuję klucza API?

Nie, jeśli korzystasz z API REST, SDK i wiersza poleceń przez publiczny serwis. Tak, jeśli chodzi o hostowany endpoint MCP pod /mcp, który bez nagłówka X-API-KEY odpowiada 401. Klucz możesz utworzyć na tej stronie po zalogowaniu.

Jaki jest limit rozmiaru pliku?

Serwis przyjmuje pliki do 500 MB każdy. Pojedyncze bezpośrednie żądanie API może mieć do 100 MiB łącznie z ramkowaniem multipart. SDK przesyła większe dane automatycznie we fragmentach, gdy łączny rozmiar przekroczy 95 MB.

Czy mogę samodzielnie hostować API?

Tak. Uruchom serwer samodzielnie i ustaw adres bazowy API na jego adres. SDK, wiersz poleceń i lokalny serwer MCP akceptują własny bazowy adres URL.

Jak zgłosić błąd?

Skopiuj pola code, reason i detail z odpowiedzi z opisem problemu, dodaj czas wysłania żądania i prześlij je przez stronę kontaktową. Nie wysyłaj samego pliku PDF, chyba że poprosi o niego wsparcie.

Czego użyć: SDK, wiersza poleceń czy MCP?

SDK wybierz w kodzie TypeScript, wiersz poleceń do skryptów i partii plików lokalnych, a MCP wtedy, gdy narzędzie wybiera agent AI. Wszystkie trzy korzystają z tego samego katalogu i tego samego serwera, więc możesz je łączyć.