Με ποιον τρόπο να χρησιμοποιήσω το PDF123 από κώδικα;
Και οι τέσσερις διεπαφές καλούν τις ίδιες λειτουργίες, οπότε μια συγχώνευση δίνει το ίδιο αποτέλεσμα σε όλες. Επιλέξτε ανάλογα με το πού εκτελείται ο κώδικάς σας.
| Διεπαφή | Ιδανική για | Εγκατάσταση ή διεύθυνση | Οδηγός |
|---|---|---|---|
| REST API | Οποιαδήποτε γλώσσα, διακομιστές, shell scripts | https://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 και Cursor | npx -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 για κάθε αρχείο.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfΗ ίδια συγχώνευση με το 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" });Η ίδια συγχώνευση με τη γραμμή εντολών:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfΠώς λειτουργεί η ταυτοποίηση;
Οι ανώνυμες κλήσεις προς το δημόσιο API δεν χρειάζονται λογαριασμό ούτε κλειδί. Στείλτε ένα κλειδί API στην κεφαλίδα X-API-KEY όταν θέλετε να αναγνωρίζεται η κίνησή σας ή όταν καλείτε το φιλοξενούμενο endpoint MCP, το οποίο απαιτεί πάντα κλειδί.
Συνδεθείτε για να δημιουργήσετε ένα κλειδί στον παρακάτω πίνακα και φυλάξτε το σε ασφαλές μέρος.
Έλεγχος της συνεδρίας σας…
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. Κάθε βήμα λαμβάνει την έξοδο του προηγούμενου.
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 ανά αρχείο |
| Σώμα ενός άμεσου αιτήματος API | 100 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_request | 400 | Μη έγκυρες παράμετροι ή σώμα multipart |
password_required | 400 | Το PDF είναι κρυπτογραφημένο και δεν στάλθηκε κωδικός |
invalid_pdf | 400 | Το αρχείο δεν είναι PDF ή είναι κατεστραμμένο· δοκιμάστε την Επισκευή PDF |
page_out_of_range | 400 | Μια σελίδα που ζητήθηκε δεν υπάρχει |
not_found | 404 | Άγνωστη διαδρομή λειτουργίας |
rate_limited | 429 | Η ποσόστωση εξαντλήθηκε· περιμένετε σύμφωνα με το Retry-After |
Ποια εργαλεία μπορώ να καλέσω πρώτα;
Αυτά τα δώδεκα εργαλεία καλύπτουν τα περισσότερα αιτήματα. Χρησιμοποιήστε τη σελίδα του εργαλείου για να το δοκιμάσετε στο πρόγραμμα περιήγησης.
| Σελίδα εργαλείου | Endpoint API | Εντολή CLI | Τι κάνει |
|---|---|---|---|
| Συγχώνευση | /general/merge-pdfs | pdfx merge | Ενώνει πολλά PDF σε ένα |
| Διαχωρισμός | /general/split-pages | pdfx split | Χωρίζει ένα PDF σε ξεχωριστά αρχεία |
| Συμπίεση | /misc/compress-pdf | pdfx compress | Επανασυμπιέζει τις ροές του PDF για να μειώσει το μέγεθος |
| Περιστροφή | /general/rotate-pdf | pdfx rotate | Αλλάζει τον προσανατολισμό των σελίδων |
| Προσθήκη κωδικού | /security/add-password | pdfx protect | Κρυπτογραφεί ένα PDF με κωδικό |
| Αφαίρεση κωδικού | /security/remove-password | pdfx unlock | Αφαιρεί την προστασία με κωδικό |
| Υδατογράφημα | /security/add-watermark | pdfx watermark | Προσθέτει υδατογράφημα κειμένου ή εικόνας |
| OCR | /misc/ocr-pdf | pdfx ocr | Διαβάζει ένα σαρωμένο PDF και επιστρέφει Markdown |
| PDF σε Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Μετατρέπει ένα PDF σε Markdown |
| PDF σε Word | /convert/pdf/word | pdfx convert-to-word | Μετατρέπει ένα PDF σε επεξεργάσιμο αρχείο Word |
| Πληροφορίες εγγράφου | /security/get-info-on-pdf | pdfx get-info | Αναφέρει μεταδεδομένα, δικαιώματα, γραμματοσειρές και δομή |
| Επισκευή | /misc/repair | pdfx 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. Και τα τρία χρησιμοποιούν τον ίδιο κατάλογο και τον ίδιο διακομιστή, οπότε μπορείτε να τα συνδυάσετε.