Come uso PDF123 dal codice?
Le quattro interfacce richiamano le stesse operazioni, quindi un'unione dà lo stesso risultato in ciascuna. Scegli in base a dove viene eseguito il tuo codice.
| Interfaccia | Ideale per | Installazione o indirizzo | Guida |
|---|---|---|---|
| API REST | Qualsiasi linguaggio, server, script di shell | https://pdf123.xyz/api/v1 | Riferimento API |
| SDK TypeScript | Codice Node, Bun e browser che richiede i tipi | npm install @pdf123/sdk | Guida all'SDK |
| Riga di comando | Terminali, job di CI, gruppi di file locali | npm install -g @pdf123/cli | Guida alla CLI |
| MCP | Agenti IA come Claude Code, Claude Desktop e Cursor | npx -y @pdf123/mcp oppure https://pdf123.xyz/mcp | Guida a MCP |
Usa l'API REST se il tuo codice non è scritto in TypeScript. Usa l'SDK se lo è, perché le opzioni degli strumenti sono tipizzate e verificate prima del caricamento. Usa la riga di comando per lavori occasionali e script di shell. Usa MCP quando deve essere un agente IA a decidere quale strumento eseguire.
Il catalogo ha 97 strumenti. 58 di questi hanno una pagina su questo sito, come Unisci PDF, Dividi PDF e Comprimi PDF. Gli altri sono operazioni del backend senza pagina web, e sono tutti disponibili nell'SDK, nella riga di comando e in MCP.
Come eseguo la mia prima richiesta?
Unisci due file con curl. La richiesta è un modulo multipart con una parte fileInput per ogni file.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfLa stessa unione con l'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" });La stessa unione con la riga di comando:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfCome funziona l'autenticazione?
Le chiamate anonime all'API pubblica non richiedono né account né chiave. Invia una chiave API nell'header X-API-KEY quando vuoi identificare il tuo traffico o chiamare l'endpoint MCP ospitato, che richiede sempre una chiave.
Accedi per creare una chiave nel pannello qui sotto e conservala in un posto sicuro.
Verifica della sessione…
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.pdfL'SDK riceve la chiave come apiKey. La riga di comando e il server MCP locale la leggono dalla variabile d'ambiente PDFX_API_KEY.
Nota
Su un server self-host, imposta la variabile d'ambiente SECURITY_CUSTOMGLOBALAPIKEY per definire una chiave accettata dal server. Vedi Self-host.
Dove trovo il riferimento dell'API?
L'API REST è documentata in due forme. Swagger UI permette di provare ogni endpoint nel browser. Il documento OpenAPI è la fonte leggibile da macchina per i generatori di client.
Ogni operazione è una POST sotto l'URL di base https://pdf123.xyz/api/v1, raggruppata per categoria. Per esempio, l'unione è /general/merge-pdfs e la compressione è /misc/compress-pdf.
Come concateno più strumenti in una sola richiesta?
POST /api/v1/pipeline accetta le parti fileInput e un campo steps. Il campo steps è un array JSON di oggetti con un op e params facoltativi. Ogni passaggio riceve l'output del passaggio precedente.
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.pdfCome ripeto una richiesta in sicurezza?
Invia un header Idempotency-Key con qualsiasi operazione. Una ripetizione della stessa richiesta entro 24 ore restituisce il primo risultato con l'header Idempotency-Replayed: true invece di eseguirla di nuovo. Usare la stessa chiave per una richiesta diversa viene rifiutato. I risultati più grandi di 32 MiB non vengono memorizzati, quindi la ripetizione di una richiesta del genere riceve 409 e richiede una nuova chiave.
Quali sono i limiti di dimensione e di frequenza?
| Limite | Valore |
|---|---|
| Dimensione dei file sul sito web | 500 MB per file |
| Corpo di una singola richiesta API diretta | 100 MiB, compreso il framing multipart |
| Caricamento a blocchi | L'SDK passa automaticamente all'API di caricamento oltre 95 MB in totale |
Le risposte includono gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta con stato 429 aggiunge Retry-After. Leggi gli header invece di presumere una quota fissa, perché un server self-host imposta i propri limiti. L'articolo del blog sul limite di dimensione della richiesta spiega l'errore che ricevi per un corpo troppo grande.
Che aspetto ha un errore?
I fallimenti restituiscono application/problem+json con i campi type, title, status, detail, code, reason e hint. Ramifica la logica su reason e ripiega su code. Il testo di detail è scritto per le persone e non contiene mai l'output grezzo dello strumento. Tutti i codici sono elencati in Codici di errore.
| Codice o reason | Stato HTTP | Significato |
|---|---|---|
bad_request | 400 | Parametri o corpo multipart non validi |
password_required | 400 | Il PDF è cifrato e non è stata inviata alcuna password |
invalid_pdf | 400 | Il file non è un PDF o è danneggiato; prova Ripara PDF |
page_out_of_range | 400 | Una pagina richiesta non esiste |
not_found | 404 | Percorso di operazione sconosciuto |
rate_limited | 429 | Quota esaurita; attendi il tempo indicato da Retry-After |
Quali strumenti posso chiamare per primi?
Questi dodici strumenti coprono la maggior parte delle richieste. Usa la pagina dello strumento per provarlo nel browser.
| Pagina dello strumento | Endpoint API | Comando CLI | Cosa fa |
|---|---|---|---|
| Unisci | /general/merge-pdfs | pdfx merge | Unisce più PDF in uno solo |
| Dividi | /general/split-pages | pdfx split | Divide un PDF in file separati |
| Comprimi | /misc/compress-pdf | pdfx compress | Ricomprime i flussi del PDF per ridurne il peso |
| Ruota | /general/rotate-pdf | pdfx rotate | Cambia l'orientamento delle pagine |
| Proteggi | /security/add-password | pdfx protect | Cifra un PDF con una password |
| Sblocca | /security/remove-password | pdfx unlock | Rimuove la protezione con password |
| Filigrana | /security/add-watermark | pdfx watermark | Aggiunge una filigrana di testo o di immagine |
| OCR | /misc/ocr-pdf | pdfx ocr | Legge un PDF scansionato e restituisce Markdown |
| PDF in Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Converte un PDF in Markdown |
| PDF in Word | /convert/pdf/word | pdfx convert-to-word | Converte un PDF in un file Word modificabile |
| Info documento | /security/get-info-on-pdf | pdfx get-info | Riporta metadati, permessi, caratteri e struttura |
| Ripara | /misc/repair | pdfx repair | Ricostruisce la struttura di un PDF danneggiato |
Gli endpoint sono relativi a https://pdf123.xyz/api/v1. Esegui pdfx list o apri il documento OpenAPI per vedere tutti i 97 strumenti.
Come uso PDF123 da un agente IA?
Un agente può usare gli strumenti in tre modi:
- Collegare un server MCP. La guida a MCP descrive il server locale
@pdf123/mcpper i file sul tuo computer e l'endpoint ospitato suhttps://pdf123.xyz/mcp. - Caricare una skill per agenti. Le skill per agenti sono file
SKILL.mdper Claude Code, Codex, Cursor e strumenti simili, una per il catalogo e una per ogni strumento. - Leggere l'indice del sito. /llms.txt elenca gli strumenti, l'API e l'endpoint MCP in testo semplice, e
/site.jsonlddescrive il sito come dati strutturati.
L'articolo del blog "Built for AI Agents, Not Just Browsers" sul blog di PDF123 spiega come si integrano l'API REST e MCP.
Posso eseguire PDF123 sul mio server?
Sì. Il backend è il programma pdfx-server, che gira in Docker. Punta l'SDK, la riga di comando o il server MCP al tuo server con PDFX_API_BASE, e i tuoi file restano nella tua rete. Vedi Self-host per la configurazione e Enterprise per le opzioni di supporto.
FAQ
L'API di PDF123 è gratuita?
Sì, per l'uso anonimo. Le chiamate all'API pubblica non richiedono né account né chiave. Le risposte del servizio ospitato includono gli header sui limiti di frequenza, così un client può rallentare prima di ricevere una risposta 429.
Mi serve una chiave API?
No per l'API REST, l'SDK e la riga di comando se usi il sito pubblico. Sì per l'endpoint MCP ospitato su /mcp, che risponde 401 senza un header X-API-KEY. Puoi creare una chiave in questa pagina dopo aver effettuato l'accesso.
Qual è il limite di dimensione dei file?
Il sito web accetta file fino a 500 MB ciascuno. Il corpo di una singola richiesta API diretta può arrivare a 100 MiB, compreso il framing multipart. L'SDK carica automaticamente a blocchi gli input più grandi, una volta che il totale supera 95 MB.
Posso eseguire l'API sul mio server?
Sì. Esegui il server per conto tuo e imposta la base dell'API sul suo indirizzo. L'SDK, la riga di comando e il server MCP locale accettano tutti un URL di base personalizzato.
Come segnalo un errore?
Copia i campi code, reason e detail dalla risposta di tipo problem, insieme all'ora della richiesta, e inviali tramite la pagina dei contatti. Non inviare il PDF stesso, a meno che l'assistenza non lo richieda.
Devo usare l'SDK, la riga di comando o MCP?
Usa l'SDK nel codice TypeScript, la riga di comando per script e gruppi di file locali, e MCP quando è un agente IA a scegliere lo strumento. Tutti e tre usano lo stesso catalogo e lo stesso server, quindi puoi combinarli.