Μετάβαση στο κύριο περιεχόμενο
PPDF123

PDF123 για προγραμματιστές: REST API, SDK, γραμμή εντολών και MCP

Η πλατφόρμα προγραμματιστών του PDF123 προσφέρει τα ίδια 97 εργαλεία PDF μέσω τεσσάρων διεπαφών: ένα REST API που περιγράφεται με OpenAPI, ένα SDK TypeScript, τη γραμμή εντολών pdfx και διακομιστές MCP για πράκτορες AI. Οι ανώνυμες κλήσεις δεν απαιτούν λογαριασμό ή κλειδί API.

Σε αυτή τη σελίδα

Με ποιον τρόπο να χρησιμοποιήσω το PDF123 από κώδικα;

Και οι τέσσερις διεπαφές καλούν τις ίδιες λειτουργίες, οπότε μια συγχώνευση δίνει το ίδιο αποτέλεσμα σε όλες. Επιλέξτε ανάλογα με το πού εκτελείται ο κώδικάς σας.

ΔιεπαφήΙδανική γιαΕγκατάσταση ή διεύθυνσηΟδηγός
REST APIΟποιαδήποτε γλώσσα, διακομιστές, shell scriptshttps://pdf123.xyz/api/v1Αναφορά API
SDK TypeScriptΚώδικας Node, Bun και προγράμματος περιήγησης που χρειάζεται τύπουςnpm install @pdf123/sdkΟδηγός SDK
Γραμμή εντολώνΤερματικά, εργασίες CI, παρτίδες τοπικών αρχείωνnpm install -g @pdf123/cliΟδηγός CLI
MCPΠράκτορες AI όπως Claude Code, Claude Desktop και Cursornpx -y @pdf123/mcp ή https://pdf123.xyz/mcpΟδηγός MCP

Χρησιμοποιήστε το REST API αν ο κώδικάς σας δεν είναι γραμμένος σε TypeScript. Χρησιμοποιήστε το SDK αν είναι, γιατί οι επιλογές κάθε εργαλείου έχουν τύπους και ελέγχονται πριν από τη μεταφόρτωση. Χρησιμοποιήστε τη γραμμή εντολών για εφάπαξ εργασίες και shell scripts. Χρησιμοποιήστε το MCP όταν ένας πράκτορας AI πρέπει να αποφασίσει ποιο εργαλείο θα εκτελέσει.

Ο κατάλογος έχει 97 εργαλεία. Τα 58 από αυτά έχουν σελίδα σε αυτόν τον ιστότοπο, όπως Συγχώνευση PDF, Διαχωρισμός PDF και Συμπίεση PDF. Τα υπόλοιπα είναι λειτουργίες του backend χωρίς σελίδα, και όλα είναι διαθέσιμα στο SDK, στη γραμμή εντολών και στο MCP.

Πώς εκτελώ το πρώτο μου αίτημα;

Συγχωνεύστε δύο αρχεία με curl. Το αίτημα είναι φόρμα multipart με ένα μέρος fileInput για κάθε αρχείο.

REST: merge two PDFsbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

Η ίδια συγχώνευση με το SDK TypeScript:

SDK: merge two PDFsts
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" });

Η ίδια συγχώνευση με τη γραμμή εντολών:

CLI: merge two PDFsbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Πώς λειτουργεί η ταυτοποίηση;

Οι ανώνυμες κλήσεις προς το δημόσιο API δεν χρειάζονται λογαριασμό ούτε κλειδί. Στείλτε ένα κλειδί API στην κεφαλίδα X-API-KEY όταν θέλετε να αναγνωρίζεται η κίνησή σας ή όταν καλείτε το φιλοξενούμενο endpoint MCP, το οποίο απαιτεί πάντα κλειδί.

Συνδεθείτε για να δημιουργήσετε ένα κλειδί στον παρακάτω πίνακα και φυλάξτε το σε ασφαλές μέρος.

Έλεγχος της συνεδρίας σας…

Call the API with a keybash
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 δέχεται το κλειδί ως apiKey. Η γραμμή εντολών και ο τοπικός διακομιστής MCP το διαβάζουν από τη μεταβλητή περιβάλλοντος PDFX_API_KEY.

Σημείωση

Σε διακομιστή που φιλοξενείτε μόνοι σας, ορίστε τη μεταβλητή περιβάλλοντος SECURITY_CUSTOMGLOBALAPIKEY για να καθορίσετε ένα κλειδί που δέχεται ο διακομιστής. Δείτε την Αυτοφιλοξενία.

Πού βρίσκεται η αναφορά του API;

Το REST API τεκμηριώνεται με δύο μορφές. Το Swagger UI σάς επιτρέπει να δοκιμάσετε κάθε endpoint στο πρόγραμμα περιήγησης. Το έγγραφο OpenAPI είναι η μηχανικά αναγνώσιμη πηγή για γεννήτριες πελατών.

Κάθε λειτουργία είναι ένα POST κάτω από τη βασική διεύθυνση https://pdf123.xyz/api/v1, ομαδοποιημένο ανά κατηγορία. Για παράδειγμα, η συγχώνευση είναι /general/merge-pdfs και η συμπίεση είναι /misc/compress-pdf.

Πώς αλυσοδένω πολλά εργαλεία σε ένα αίτημα;

Το POST /api/v1/pipeline δέχεται τα μέρη fileInput και ένα πεδίο steps. Το πεδίο steps είναι πίνακας JSON με αντικείμενα που έχουν ένα op και προαιρετικά params. Κάθε βήμα λαμβάνει την έξοδο του προηγούμενου.

Merge, then compress, in one requestbash
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

Πώς επαναλαμβάνω ένα αίτημα με ασφάλεια;

Στείλτε μια κεφαλίδα Idempotency-Key σε οποιαδήποτε λειτουργία. Η επανάληψη του ίδιου αιτήματος μέσα σε 24 ώρες επιστρέφει το πρώτο αποτέλεσμα με την κεφαλίδα Idempotency-Replayed: true, αντί να εκτελεστεί ξανά. Η χρήση του ίδιου κλειδιού για διαφορετικό αίτημα απορρίπτεται. Αποτελέσματα μεγαλύτερα από 32 MiB δεν αποθηκεύονται, οπότε η επανάληψη ενός τέτοιου αιτήματος απαντά 409 και χρειάζεται νέο κλειδί.

Ποια είναι τα όρια μεγέθους και ρυθμού;

ΌριοΤιμή
Μέγεθος αρχείου στον ιστότοπο500 MB ανά αρχείο
Σώμα ενός άμεσου αιτήματος API100 MiB, συμπεριλαμβανομένου του πλαισίου multipart
Μεταφόρτωση σε τμήματαΤο SDK περνά αυτόματα στο API μεταφόρτωσης όταν το σύνολο ξεπερνά τα 95 MB

Οι απαντήσεις περιέχουν τις κεφαλίδες X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset. Μια απάντηση με κατάσταση 429 προσθέτει το Retry-After. Διαβάστε τις κεφαλίδες αντί να υποθέτετε σταθερό όριο, γιατί ένας διακομιστής που φιλοξενείτε μόνοι σας ορίζει τα δικά του όρια. Το άρθρο του ιστολογίου για το όριο μεγέθους αιτήματος εξηγεί το σφάλμα που παίρνετε για υπερβολικά μεγάλο σώμα.

Πώς μοιάζει ένα σφάλμα;

Οι αποτυχίες επιστρέφουν application/problem+json με τα πεδία type, title, status, detail, code, reason και hint. Διακλαδώστε με βάση το reason και καταφύγετε στο code. Το κείμενο detail γράφεται για ανθρώπους και δεν περιέχει ποτέ ανεπεξέργαστη έξοδο του εργαλείου. Όλοι οι κωδικοί παρατίθενται στους Κωδικούς σφαλμάτων.

Κωδικός ή αιτίαΚατάσταση HTTPΣημασία
bad_request400Μη έγκυρες παράμετροι ή σώμα multipart
password_required400Το PDF είναι κρυπτογραφημένο και δεν στάλθηκε κωδικός
invalid_pdf400Το αρχείο δεν είναι PDF ή είναι κατεστραμμένο· δοκιμάστε την Επισκευή PDF
page_out_of_range400Μια σελίδα που ζητήθηκε δεν υπάρχει
not_found404Άγνωστη διαδρομή λειτουργίας
rate_limited429Η ποσόστωση εξαντλήθηκε· περιμένετε σύμφωνα με το Retry-After

Ποια εργαλεία μπορώ να καλέσω πρώτα;

Αυτά τα δώδεκα εργαλεία καλύπτουν τα περισσότερα αιτήματα. Χρησιμοποιήστε τη σελίδα του εργαλείου για να το δοκιμάσετε στο πρόγραμμα περιήγησης.

Σελίδα εργαλείουEndpoint APIΕντολή CLIΤι κάνει
Συγχώνευση/general/merge-pdfspdfx mergeΕνώνει πολλά PDF σε ένα
Διαχωρισμός/general/split-pagespdfx splitΧωρίζει ένα PDF σε ξεχωριστά αρχεία
Συμπίεση/misc/compress-pdfpdfx compressΕπανασυμπιέζει τις ροές του PDF για να μειώσει το μέγεθος
Περιστροφή/general/rotate-pdfpdfx rotateΑλλάζει τον προσανατολισμό των σελίδων
Προσθήκη κωδικού/security/add-passwordpdfx protectΚρυπτογραφεί ένα PDF με κωδικό
Αφαίρεση κωδικού/security/remove-passwordpdfx unlockΑφαιρεί την προστασία με κωδικό
Υδατογράφημα/security/add-watermarkpdfx watermarkΠροσθέτει υδατογράφημα κειμένου ή εικόνας
OCR/misc/ocr-pdfpdfx ocrΔιαβάζει ένα σαρωμένο PDF και επιστρέφει Markdown
PDF σε Markdown/convert/pdf/markdownpdfx pdf-to-markdownΜετατρέπει ένα PDF σε Markdown
PDF σε Word/convert/pdf/wordpdfx convert-to-wordΜετατρέπει ένα PDF σε επεξεργάσιμο αρχείο Word
Πληροφορίες εγγράφου/security/get-info-on-pdfpdfx get-infoΑναφέρει μεταδεδομένα, δικαιώματα, γραμματοσειρές και δομή
Επισκευή/misc/repairpdfx repairΞαναχτίζει τη δομή ενός κατεστραμμένου PDF

Τα endpoints είναι σχετικά με το https://pdf123.xyz/api/v1. Εκτελέστε pdfx list ή ανοίξτε το έγγραφο OpenAPI για να δείτε και τα 97 εργαλεία.

Πώς χρησιμοποιώ το PDF123 από πράκτορα AI;

Ένας πράκτορας μπορεί να χρησιμοποιήσει τα εργαλεία με τρεις τρόπους:

  • Συνδέοντας έναν διακομιστή MCP. Ο οδηγός MCP καλύπτει τον τοπικό διακομιστή @pdf123/mcp για αρχεία στον υπολογιστή σας και το φιλοξενούμενο endpoint στο https://pdf123.xyz/mcp.
  • Φορτώνοντας ένα skill πράκτορα. Τα Skills για πράκτορες είναι αρχεία SKILL.md για Claude Code, Codex, Cursor και παρόμοια εργαλεία, ένα για τον κατάλογο και ένα για κάθε εργαλείο.
  • Διαβάζοντας το ευρετήριο του ιστότοπου. Το /llms.txt παραθέτει σε απλό κείμενο τα εργαλεία, το API και το endpoint MCP, και το /site.jsonld περιγράφει τον ιστότοπο ως δομημένα δεδομένα.

Το άρθρο «Built for AI Agents, Not Just Browsers» στο ιστολόγιο του PDF123 εξηγεί πώς συνδυάζονται το REST API και το MCP.

Μπορώ να εκτελέσω το PDF123 στον δικό μου διακομιστή;

Ναι. Το backend είναι το πρόγραμμα pdfx-server, που εκτελείται σε Docker. Κατευθύνετε το SDK, τη γραμμή εντολών ή τον διακομιστή MCP σε αυτό με το PDFX_API_BASE, και τα αρχεία σας μένουν στο δίκτυό σας. Δείτε την Αυτοφιλοξενία για τη ρύθμιση και τις Επιχειρήσεις για επιλογές υποστήριξης.

Συχνές ερωτήσεις

Είναι δωρεάν το API του PDF123;

Ναι, για ανώνυμη χρήση. Οι κλήσεις προς το δημόσιο API δεν χρειάζονται λογαριασμό ή κλειδί. Οι απαντήσεις του φιλοξενούμενου API περιέχουν κεφαλίδες ορίου ρυθμού, ώστε ένας πελάτης να επιβραδύνει πριν λάβει απάντηση 429.

Χρειάζομαι κλειδί API;

Όχι για το REST API, το SDK και τη γραμμή εντολών όταν χρησιμοποιείτε τον δημόσιο ιστότοπο. Ναι για το φιλοξενούμενο endpoint MCP στο /mcp, που απαντά 401 χωρίς κεφαλίδα X-API-KEY. Μπορείτε να δημιουργήσετε κλειδί σε αυτή τη σελίδα αφού συνδεθείτε.

Ποιο είναι το όριο μεγέθους αρχείου;

Ο ιστότοπος δέχεται αρχεία έως 500 MB το καθένα. Το σώμα ενός άμεσου αιτήματος API μπορεί να φτάσει τα 100 MiB, συμπεριλαμβανομένου του πλαισίου multipart. Το SDK ανεβάζει αυτόματα σε τμήματα τις μεγαλύτερες εισόδους όταν το σύνολο ξεπερνά τα 95 MB.

Μπορώ να φιλοξενήσω μόνος μου το API;

Ναι. Εκτελέστε τον διακομιστή μόνοι σας και ορίστε ως βάση του API τη διεύθυνσή του. Το SDK, η γραμμή εντολών και ο τοπικός διακομιστής MCP δέχονται όλα προσαρμοσμένη βασική διεύθυνση URL.

Πώς αναφέρω ένα σφάλμα;

Αντιγράψτε τα πεδία code, reason και detail από την απάντηση προβλήματος, μαζί με την ώρα του αιτήματος, και στείλτε τα μέσω της σελίδας επικοινωνίας. Μην στείλετε το ίδιο το PDF, εκτός αν το ζητήσει η υποστήριξη.

Να χρησιμοποιήσω το SDK, τη γραμμή εντολών ή το MCP;

Χρησιμοποιήστε το SDK μέσα σε κώδικα TypeScript, τη γραμμή εντολών για scripts και παρτίδες τοπικών αρχείων, και το MCP όταν το εργαλείο το επιλέγει ένας πράκτορας AI. Και τα τρία χρησιμοποιούν τον ίδιο κατάλογο και τον ίδιο διακομιστή, οπότε μπορείτε να τα συνδυάσετε.