PDFDocumentazione per sviluppatori
Tutti gli strumenti di raiai.cloud usano la stessa porta d’ingresso: una sola chiamata HTTP che riceve il nome dello strumento, i file e le opzioni, e restituisce il file lavorato. È la stessa che usa il sito quando premi “Elabora”: non c’è un’API separata, né una versione “ridotta” per gli sviluppatori.
POST https://raiai.cloud/wp-json/raiai/v1/process
Non serve una chiave, non serve un account, non c’è una registrazione da fare. Quello che vedi qui sotto è stato provato davvero il 28 settembre 2026, con i comandi che trovi scritti nel capitolo delle prove: se un comando è qui, ha risposto 200 e ha prodotto il file che diciamo.
Provalo adesso
Serve curl (è già su Linux e macOS; su Windows c’è in PowerShell). Questo comando unisce due PDF e salva il risultato in unito.pdf:
curl -o unito.pdf -X POST "https://raiai.cloud/wp-json/raiai/v1/process" \ -F "tool=merge" \ -F "files[]=@primo.pdf" \ -F "files[]=@secondo.pdf"
La risposta è il file, non un JSON: curl lo scrive direttamente su unito.pdf. Il nome che il server suggerisce è nell’intestazione Content-Disposition (per l’unione: raiai-merged.pdf).
Come è fatta la richiesta
- Metodo: POST obbligatorio. Una GET sull’indirizzo risponde 404, perché non c’è nulla da leggere.
- Tipo:
multipart/form-data. È lo stesso tipo di un modulo con allegati: incurlsi usa-F, in Pythonfiles=direquests, in PHPcurl_setopt(CURLOPT_POSTFIELDS, $dati)con un array. tool: il nome del motore che deve lavorare il file. La tabella completa è in fondo a questa pagina.files[]: uno o più file. Si ripete il campo per ogni file, nell’ordine in cui devono essere usati (per l’unione l’ordine conta).- Opzioni: si aggiungono come campi normali, con il nome che trovi nella tabella (
pages,level,rotation…). Se non le metti, si usano i valori predefiniti. - Codici QR e codici a barre (
qr,barcode) sono gli unici due strumenti che non hanno bisogno di un file: il contenuto arriva dal campotext.
Le prove fatte, con i risultati veri
Questi comandi sono stati eseguiti uno per uno il 28 settembre 2026 contro il sito in produzione. Accanto c’è quello che è tornato indietro.
1. Unire due PDF (merge)
curl -o unito.pdf -D intestazioni.txt -X POST "https://raiai.cloud/wp-json/raiai/v1/process" \ -F "tool=merge" -F "files[]=@prova-uno.pdf" -F "files[]=@prova-due.pdf"
Risultato: HTTP 200, content-type: application/pdf, content-disposition: attachment; filename="raiai-merged.pdf", 1.088 byte. Aprendo il file: 2 pagine, con il testo di entrambi i documenti di partenza nell’ordine giusto.
2. Generare un codice QR (qr)
curl -o codice.png -X POST "https://raiai.cloud/wp-json/raiai/v1/process" \ -F "tool=qr" -F "text=https://raiai.cloud" -F "size=512" -F "format=png"
Risultato: HTTP 200, image/png, immagine di 522×522 pixel in scala di grigi, 538 byte. Il file esce un po’ più grande del valore chiesto perché il codice include il margine bianco di silenzio attorno (con size=200 escono 209 pixel).
Con -F "format=svg" torna un SVG vettoriale (1.269 byte) e con -F "format=pdf" un PDF di una pagina (1.413 byte): utili per la stampa.
3. Comprimere un PDF (compress)
curl -o compresso.pdf -X POST "https://raiai.cloud/wp-json/raiai/v1/process" \ -F "tool=compress" -F "level=ebook" -F "files[]=@prova-uno.pdf"
Risultato: HTTP 200, application/pdf, 2.703 byte, una pagina. Il campo level accetta screen (compressione media), ebook (massima compressione), printer (alta qualità) e prepress (qualità massima).
4. PDF in immagini (pdf2img)
curl -o pagina.png -X POST "https://raiai.cloud/wp-json/raiai/v1/process" \ -F "tool=pdf2img" -F "format=png" -F "dpi=100" -F "files[]=@prova-uno.pdf"
Risultato: HTTP 200, image/png, 827×1170 pixel. format accetta jpeg o png; dpi decide la risoluzione (più alto = file più pesante).
5. Due immagini in un PDF (img2pdf)
curl -o foto.pdf -X POST "https://raiai.cloud/wp-json/raiai/v1/process" \ -F "tool=img2pdf" -F "files[]=@foto-uno.png" -F "files[]=@foto-due.png"
Risultato: HTTP 200, application/pdf, 2 pagine. È lo stesso motore che sta dietro Scansione in PDF.
6. Codice a barre (barcode)
curl -o ean13.png -X POST "https://raiai.cloud/wp-json/raiai/v1/process" \ -F "tool=barcode" -F "text=800123456789" -F "format=ean13"
Risultato: HTTP 200, image/png, 523×223 pixel. format accetta ean13, ean8, code128, code39, itf, upca, gs1_128.
7. Proteggere un PDF con password (protect)
curl -o protetto.pdf -X POST "https://raiai.cloud/wp-json/raiai/v1/process" \ -F "tool=protect" -F "password=prova1234" -F "files[]=@prova-uno.pdf"
Risultato: HTTP 200, application/pdf. Il file prodotto contiene un blocco di cifratura e si apre con la password indicata.
8. Word in PDF con LibreOffice (office2pdf)
curl -o documento.pdf -X POST "https://raiai.cloud/wp-json/raiai/v1/process" \ -F "tool=office2pdf" -F "files[]=@relazione.docx"
Risultato (prova fatta con un file di testo, per non aspettare la conversione di un documento vero): HTTP 200, application/pdf, 14.842 byte. Accetta doc, docx, odt, rtf, txt, xls, xlsx, ods, csv, ppt, pptx, odp, html. Lo stesso motore sta dietro PDF in Word, PDF in Excel e PDF in PowerPoint.
Altri strumenti provati nello stesso giro
splitconpages=1→ 200, PDF di una pagina.rotateconrotation=90→ 200, PDF ruotato.watermarkcontext=BOZZA→ 200, filigrana applicata.pdf_info(Referto PDF) → 200, PDF con il referto del file.metadatacontext=Documento di prova→ 200, metadati ripuliti.pdf2txt→ 200,text/plain, testo estratto.img_compressconquality=60su una PNG → 200, immagine compressa.chiedicon una domanda su un PDF → 200 in 0,5 secondi, PDF con i passaggi trovati.translatecontarget=inglesesu un PDF di 2 pagine → 200 in 1 minuto e 26 secondi. È lo strumento più lento del sito, perché il modello linguistico gira sulla nostra macchina in CPU: metti un timeout generoso, almeno 5 minuti.
La risposta quando va bene
Non è un JSON: è il file. Il corpo della risposta sono i byte del risultato, e le informazioni utili stanno nelle intestazioni:
HTTP/2 200 content-type: application/pdf content-disposition: attachment; filename="raiai-merged.pdf" content-length: 1088 cache-control: no-cache, must-revalidate, max-age=0, no-store, private x-robots-tag: noindex
Il content-type cambia con il risultato: application/pdf, image/png, image/svg+xml, text/plain, application/zip (per gli strumenti che producono più file). Il nome del file è in content-disposition: leggilo se vuoi salvare con il nome giusto.
La risposta quando va male
In caso di errore la risposta è un JSON con status e message. Questi sono gli errori che abbiamo visto davvero, non quelli che immaginiamo:
| Codice | Cosa succede | Risposta |
|---|---|---|
| 400 | Non hai allegato nessun file | {"status":"error","message":"Nessun file ricevuto"} |
| 400 | Manca il campo tool |
{"status":"error","message":"Parametro tool mancante"} |
| 400 | Formato non ammesso per quello strumento | Formato .txt non ammesso per questo strumento. Ammessi: … |
| 400 | Il nome del motore non esiste | {"status":"error","message":"Tool sconosciuto: non_esiste"} |
| 400 | Il file non è leggibile dal motore | {"status":"error","message":"Stream has ended unexpectedly"} |
| 400 | Il PDF richiede una password per aprirsi | {"status":"error","message":"Sblocco fallito: File has not been decrypted"} |
| 500 | Guasto del nostro server (il caso raro) | {"status":"error","message":"…"} |
Dal 28 settembre 2026 la distinzione è netta: 400 vuol dire «la richiesta non va bene» (manca un parametro, il formato è sbagliato, il file non si legge, il motore non esiste, il PDF è protetto da password), 500 vuol dire «si è rotto qualcosa da noi» e in quel caso conviene riprovare. Tutti i casi della tabella che prima rispondevano 500 per colpa della richiesta ora rispondono 400, misurati uno per uno.
Due cose da sapere sugli errori. La prima: i codici non sono sempre precisi. Se sbagli il nome dello strumento o il formato del file, il motore risponde 500 anche se la colpa è della richiesta: guarda sempre il campo message, non solo il numero. La seconda: anche gli errori arrivano subito, senza file parziali — quello che il motore aveva prodotto a metà viene cancellato insieme alla cartella di lavoro.
Limiti veri della chiamata
- Dimensione: 512 MB per richiesta (somma di tutti i file allegati). È il tetto configurato sul server: sopra quella soglia la richiesta viene rifiutata prima di arrivare al motore.
- Tempo: 300 secondi per la richiesta normale. Gli strumenti che girano su Python hanno un tetto più alto (fino a 15 minuti) per non interrompere le traduzioni. Se chiami
translate, metti un timeout di almeno 5 minuti. - Nessuna quota: oggi non ci sono chiavi, non ci sono contatori e non c’è un numero massimo di chiamate. Non significa che si possa martellare il servizio: le stesse macchine servono il sito ai visitatori.
- Un lavoro per richiesta: per elaborare 100 file fai 100 chiamate (o usa una chiamata per ogni gruppo di file che vuoi unire insieme).
Chiamarla da un programma
Python
import requests
with open("primo.pdf", "rb") as a, open("secondo.pdf", "rb") as b:
risposta = requests.post(
"https://raiai.cloud/wp-json/raiai/v1/process",
data={"tool": "merge"},
files=[("files[]", ("primo.pdf", a, "application/pdf")),
("files[]", ("secondo.pdf", b, "application/pdf"))],
timeout=300,
)
risposta.raise_for_status()
open("unito.pdf", "wb").write(risposta.content)
PHP
$ch = curl_init("https://raiai.cloud/wp-json/raiai/v1/process");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 300);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
"tool" => "compress",
"level" => "ebook",
"files[]" => new CURLFile("/percorso/documento.pdf"),
]);
$pdf = curl_exec($ch);
file_put_contents("/percorso/compresso.pdf", $pdf);
Dentro una pagina web (JavaScript)
Una chiamata fetch() verso questo indirizzo da un altro sito non funziona: la risposta dell’elaborazione non porta l’intestazione Access-Control-Allow-Origin, quindi il browser blocca la lettura del file (la verifica preliminare passa, la risposta no). Non è una svista nascosta: la risposta viene inviata direttamente, saltando il giro normale di WordPress, e quell’intestazione non ci finisce.
Se ti serve dall’interfaccia di un tuo sito, fai passare la chiamata da un tuo programma sul server (PHP, Python, Node): il tuo script parla con raiai.cloud, il browser parla con il tuo script. Così funziona senza intoppi.
Elenco degli strumenti: il nome da usare in tool
Attenzione a non confondere due nomi diversi: l’indirizzo pubblico della pagina web (/strumenti/unisci-pdf/) e il nome del motore da mettere nel campo tool (merge). Nella tabella ci sono entrambi.
Le opzioni crescono di settimana in settimana. Nella colonna “Opzioni” qui sotto c’è il minimo che serve per iniziare; l’elenco completo e aggiornato è il modulo della pagina web di ogni strumento (per esempio /strumenti/dividi-pdf/ per Dividi PDF): i nomi dei campi che vedi lì sono gli stessi da usare nella chiamata.
I 50 strumenti pubblici sono serviti da 47 motori: alcuni motori reggono più indirizzi — per esempio office2pdf sta dietro Word in PDF, PowerPoint in PDF ed Excel in PDF.
| Nome | Campo tool |
File | Opzioni | Pagina |
|---|---|---|---|---|
| Unisci PDF | merge |
più file | — | unisci-pdf |
| Dividi PDF | split |
un file | pages |
dividi-pdf |
| Comprimi PDF | compress |
un file | level |
comprimi-pdf |
| Ruota PDF | rotate |
un file | rotation, pages |
ruota-pdf |
| Organizza PDF | organize |
un file | pages |
organizza-pdf |
| Numero di pagine | page_numbers |
un file | — | numero-di-pagine |
| Filigrana | watermark |
un file | text |
filigrana |
| Firma PDF | sign |
un file | text |
firma-pdf |
| Proteggi PDF | protect |
un file | password |
proteggi-pdf |
| Sblocca PDF | unlock |
un file | — (vedi nota) | sblocca-pdf |
| Ripara PDF | repair |
un file | — | ripara-pdf |
| Ritaglia PDF | crop |
un file | crop |
ritaglia-pdf |
| Censura PDF | redact |
un file | redact |
censura-pdf |
| Modifica PDF | edit |
un file | text |
modifica-pdf |
| PDF in PDF/A | pdfa |
un file | — | pdf-in-pdf-a |
| Togli pagine vuote | blank_pages |
un file | — | togli-pagine-vuote |
| PDF per il web | linearize |
un file | — | pdf-per-il-web |
| Estrai note | annotations |
un file | — | estrai-note |
| Pagine per foglio | nup |
un file | pages |
pagine-per-foglio |
| Cambia formato | pagesize |
un file | format |
cambia-formato |
| Pulisci metadati | metadata |
un file | text |
pulisci-metadati |
| Word in PDF | office2pdf |
un file | — | word-in-pdf |
| PowerPoint in PDF | office2pdf |
un file | — | powerpoint-in-pdf |
| Excel in PDF | office2pdf |
un file | — | excel-in-pdf |
| PDF in Word | pdf2word |
un file | — | pdf-in-word |
| PDF in Excel | pdf2excel |
un file | — | pdf-in-excel |
| PDF in PowerPoint | pdf2ppt |
un file | — | pdf-in-powerpoint |
| HTML in PDF | html2pdf |
un file | — | html-in-pdf |
| PDF in JPG | pdf2img |
un file | format, dpi |
pdf-in-jpg |
| JPG in PDF | img2pdf |
più file | — | jpg-in-pdf |
| Scansione in PDF | img2pdf |
più file | — | scansione-in-pdf |
| PDF in Testo | pdf2txt |
un file | — | pdf-in-testo |
| PDF in Markdown | markdown |
un file | — | pdf-in-markdown |
| Estrai immagini | extract_images |
un file | — | estrai-immagini |
| OCR PDF | ocr |
un file | lang |
ocr-pdf |
| Confronta PDF | compare |
due file | — | confronta-pdf |
| Riassumi PDF | summarize |
un file | size (quante frasi) |
riassumi-pdf |
| Traduci PDF | translate |
un file | target |
traduci-pdf |
| Chiedi al PDF | chiedi |
un file | text (la domanda) |
chiedi-al-pdf |
| Referto PDF | pdf_info |
un file | — | referto-pdf |
| Codice QR | qr |
nessun file | text, size, format |
codice-qr |
| Codice a barre | barcode |
nessun file | text, format |
codice-a-barre |
| Comprimi immagine | img_compress |
un file | quality |
comprimi-immagine |
| Ridimensiona immagine | img_resize |
un file | size |
ridimensiona-immagine |
| Converti immagine | img_convert |
un file | format |
converti-immagine |
| Ruota immagine | img_rotate |
un file | rotation |
ruota-immagine |
| Ritaglia immagine | img_crop |
un file | crop |
ritaglia-immagine |
| Filigrana immagine | img_watermark |
un file | text |
filigrana-immagine |
| Bianco e nero | img_grayscale |
un file | — | bianco-e-nero |
| Miniatura | img_thumbnail |
un file | size |
miniatura |
Due cose da sapere prima di appoggiarti a questo servizio
- Il servizio è aperto e senza chiave. Oggi chiunque può chiamarlo: per noi è una scelta, perché rende utile l’API a chi vuole solo provarla. Se ti serve per un volume importante — migliaia di file al giorno — scrivici prima: così sappiamo cosa aspettarci e non ci troviamo il sito lento per i visitatori.
- Le funzioni cambiano in fretta. Questo sito cresce di settimane in settimane: se un campo o un comportamento non corrisponde a quello che leggi qui, la colpa è del documento che è invecchiato, non tua. Scrivicelo e lo aggiorniamo.
Un’ultima nota onesta su unlock: Sblocca PDF funziona sui PDF protetti da permessi (niente stampa, niente copia), mentre su un file che chiede una password per aprirsi restituisce un errore, perché il motore non usa il campo password. Lo sistemeremo; fino ad allora, non contarci in un automatismo.
Serve aiuto?
Se ti serve una mano per far funzionare una chiamata, o vuoi uno strumento che non c’è, scrivi a info@rairaiai.com raccontando cosa stai costruendo e cosa ti aspetti. Le richieste degli sviluppatori sono quelle che pesiamo di più quando decidiamo cosa fare dopo.