Vai al contenuto principale
PPDF123

PDF123 per sviluppatori: API REST, SDK, riga di comando e MCP

La piattaforma per sviluppatori di PDF123 offre gli stessi 97 strumenti PDF attraverso quattro interfacce: un'API REST descritta con OpenAPI, un SDK TypeScript, la riga di comando pdfx e server MCP per agenti IA. Le chiamate anonime non richiedono account né chiave API.

In questa pagina

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.

InterfacciaIdeale perInstallazione o indirizzoGuida
API RESTQualsiasi linguaggio, server, script di shellhttps://pdf123.xyz/api/v1Riferimento API
SDK TypeScriptCodice Node, Bun e browser che richiede i tipinpm install @pdf123/sdkGuida all'SDK
Riga di comandoTerminali, job di CI, gruppi di file localinpm install -g @pdf123/cliGuida alla CLI
MCPAgenti IA come Claude Code, Claude Desktop e Cursornpx -y @pdf123/mcp oppure https://pdf123.xyz/mcpGuida 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.

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

La stessa unione con l'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" });

La stessa unione con la riga di comando:

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

Come 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…

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

L'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.

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

Come 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?

LimiteValore
Dimensione dei file sul sito web500 MB per file
Corpo di una singola richiesta API diretta100 MiB, compreso il framing multipart
Caricamento a blocchiL'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 reasonStato HTTPSignificato
bad_request400Parametri o corpo multipart non validi
password_required400Il PDF è cifrato e non è stata inviata alcuna password
invalid_pdf400Il file non è un PDF o è danneggiato; prova Ripara PDF
page_out_of_range400Una pagina richiesta non esiste
not_found404Percorso di operazione sconosciuto
rate_limited429Quota 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 strumentoEndpoint APIComando CLICosa fa
Unisci/general/merge-pdfspdfx mergeUnisce più PDF in uno solo
Dividi/general/split-pagespdfx splitDivide un PDF in file separati
Comprimi/misc/compress-pdfpdfx compressRicomprime i flussi del PDF per ridurne il peso
Ruota/general/rotate-pdfpdfx rotateCambia l'orientamento delle pagine
Proteggi/security/add-passwordpdfx protectCifra un PDF con una password
Sblocca/security/remove-passwordpdfx unlockRimuove la protezione con password
Filigrana/security/add-watermarkpdfx watermarkAggiunge una filigrana di testo o di immagine
OCR/misc/ocr-pdfpdfx ocrLegge un PDF scansionato e restituisce Markdown
PDF in Markdown/convert/pdf/markdownpdfx pdf-to-markdownConverte un PDF in Markdown
PDF in Word/convert/pdf/wordpdfx convert-to-wordConverte un PDF in un file Word modificabile
Info documento/security/get-info-on-pdfpdfx get-infoRiporta metadati, permessi, caratteri e struttura
Ripara/misc/repairpdfx repairRicostruisce 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/mcp per i file sul tuo computer e l'endpoint ospitato su https://pdf123.xyz/mcp.
  • Caricare una skill per agenti. Le skill per agenti sono file SKILL.md per 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.jsonld descrive 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.