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.
| Interfejs | Najlepszy do | Instalacja lub adres | Przewodnik |
|---|---|---|---|
| API REST | Dowolnego języka, serwerów, skryptów powłoki | https://pdf123.xyz/api/v1 | Dokumentacja API |
| SDK TypeScript | Kodu Node, Bun i przeglądarki, który potrzebuje typów | npm install @pdf123/sdk | Przewodnik po SDK |
| Wiersz poleceń | Terminali, zadań CI, partii plików lokalnych | npm install -g @pdf123/cli | Przewodnik po CLI |
| MCP | Agentów AI, takich jak Claude Code, Claude Desktop i Cursor | npx -y @pdf123/mcp lub https://pdf123.xyz/mcp | Przewodnik 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.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfTo samo połączenie w SDK TypeScript:
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ń:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfJak 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…
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.pdfSDK 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.
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.pdfJak 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ń?
| Limit | Wartość |
|---|---|
| Rozmiar pliku w serwisie | 500 MB na plik |
| Jedno bezpośrednie żądanie API | 100 MiB, łącznie z ramkowaniem multipart |
| Przesyłanie we fragmentach | SDK 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 przyczyna | Status HTTP | Znaczenie |
|---|---|---|
bad_request | 400 | Nieprawidłowe parametry lub treść multipart |
password_required | 400 | PDF jest zaszyfrowany, a hasło nie zostało wysłane |
invalid_pdf | 400 | Plik nie jest PDF-em lub jest uszkodzony; spróbuj Napraw PDF |
page_out_of_range | 400 | Żądana strona nie istnieje |
not_found | 404 | Nieznana ścieżka operacji |
rate_limited | 429 | Limit 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ędzia | Endpoint API | Polecenie CLI | Co robi |
|---|---|---|---|
| Połącz | /general/merge-pdfs | pdfx merge | Łączy kilka plików PDF w jeden |
| Podziel | /general/split-pages | pdfx split | Dzieli PDF na osobne pliki |
| Kompresuj | /misc/compress-pdf | pdfx compress | Kompresuje strumienie PDF ponownie, aby zmniejszyć rozmiar |
| Obróć | /general/rotate-pdf | pdfx rotate | Zmienia orientację stron |
| Zabezpiecz | /security/add-password | pdfx protect | Szyfruje PDF hasłem |
| Odblokuj | /security/remove-password | pdfx unlock | Usuwa ochronę hasłem |
| Znak wodny | /security/add-watermark | pdfx watermark | Dodaje znak wodny z tekstu lub obrazu |
| OCR | /misc/ocr-pdf | pdfx ocr | Odczytuje zeskanowany PDF i zwraca Markdown |
| PDF do Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Konwertuje PDF na Markdown |
| PDF do Worda | /convert/pdf/word | pdfx convert-to-word | Konwertuje PDF na edytowalny plik Word |
| Informacje o dokumencie | /security/get-info-on-pdf | pdfx get-info | Podaje metadane, uprawnienia, czcionki i strukturę |
| Napraw | /misc/repair | pdfx repair | Odbudowuje 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/mcpdla plików na Twoim komputerze oraz hostowany endpoint pod adresemhttps://pdf123.xyz/mcp. - Załaduj skill agenta. Skille dla agentów to pliki
SKILL.mddla 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.jsonldopisuje 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ć.