SDK di conversione file#

Librerie client ufficiali per l'API EnConvert, pubblicate per dieci linguaggi: Node.js, Python, Go, Java, PHP, Ruby, C#, Rust, Kotlin e Swift. Ogni SDK copre le stesse due superfici dietro un'unica chiave API. La superficie di conversione trasforma file e URL in altri formati, mentre la superficie di web intelligence V2 percepisce, scopre, cerca, distilla, ingerisce e sorveglia pagine web live. Ogni client espone quegli endpoint come metodi tipizzati, gestisce l'autenticazione e restituisce URL di download pre-firmati.

SDK disponibili#

Tutti e dieci sono rilasciati con licenza MIT.

Scegli il tuo linguaggio#

• Node.js / TypeScript: Node 18+, zero dipendenze runtime, build ESM e CJS duali, definizioni di tipo complete.
• Python: Python 3.9+, dataclass tipizzate, marcatore py.typed incluso per mypy.
• Go: Go 1.21+, solo libreria standard, nessuna dipendenza di terze parti.
• Java: Java 17+, una sola dipendenza (Gson), HTTP tramite l'HttpClient del JDK.
• PHP: PHP 8.1+, installato con Composer, autoload PSR-4.
• Ruby: Ruby 3.0+, distribuito come gem enconvert.
• C# / .NET: .NET 8+, metodi async ovunque, tipi riferimento nullable abilitati.
• Rust: un client bloccante costruito su reqwest, quindi non serve alcun runtime async.
• Kotlin: JDK 17+, data class idiomatiche e kotlinx.serialization.
• Swift: macOS 12+, iOS 15+, tvOS 15+ e watchOS 8+, con metodi async await.

Non stai scrivendo codice? La CLI copre la stessa API dal terminale, il server MCP la collega a Claude, Cursor e Windsurf, e il nodo n8n la inserisce in un workflow.

Perché usare un SDK?#

Chiamare direttamente l'API REST funziona, e gli SDK aggiungono quattro cose in più:

• Opzioni type-safe. Autocompletamento dell'editor per ogni parametro di ogni endpoint, così un errore di battitura nel nome di un campo fallisce già in compilazione o all'import invece di tornare come un 422.
• Recupero automatico dei timeout. I render URL-to-PDF pesanti e i documenti di grandi dimensioni a volte superano il timeout del reverse-proxy anche quando la conversione riesce sul server. Gli SDK generano un job_id lato client, lo inviano con la richiesta e ripiegano silenziosamente sul polling di GET /v1/convert/status/{job_id} se la chiamata originale restituisce 5xx. Tu non scrivi codice aggiuntivo.
• Download in streaming. Punta un metodo verso un percorso locale e l'SDK trasmette la risposta direttamente su disco con backpressure, così l'uso della memoria resta costante per quanto grande sia l'output.
• Errori coerenti. Una piccola gerarchia di eccezioni ti permette di intercettare per classe invece di analizzare i codici di stato a mano.

Le due superfici#

Ogni SDK divide i suoi metodi allo stesso modo.

Ogni render V2 porta con sé anche un punteggio render_quality da 0.0 a 1.0. Una pagina bloccata, un interstiziale di sfida anti-bot o uno shell vuoto di una single-page app tornano segnalati con un punteggio basso e con degli avvisi invece di passare in silenzio come contenuto reale, così una lettura sbagliata non entra mai di nascosto nel contesto di un agente.

Ottieni una chiave API#

Ogni SDK ha bisogno di una chiave API privata (sk_...). Generane una dalla dashboard e passala al costruttore, leggendola da una variabile d'ambiente o dal tuo secret manager. Non scrivere mai una chiave privata hardcoded e non distribuirla nel codice lato client. Il codice del browser dovrebbe invece usare una chiave pubblica (pk_) con un JWT, come descritto in Chiavi pubbliche e JWT.

Domande frequenti#

Quali linguaggi hanno un SDK ufficiale per la conversione di file?#

Dieci: Node.js e TypeScript, Python, Go, Java, PHP, Ruby, C# e .NET, Rust, Kotlin e Swift. Tutti e dieci sono ufficiali, con licenza MIT, e seguono la stessa API REST, quindi una funzionalità che arriva nell'API è raggiungibile da ciascuno di essi.

Perché usare un SDK invece di chiamare direttamente l'API REST di conversione file?#

Gli SDK aggiungono opzioni type-safe con autocompletamento dell'editor, recupero automatico dei timeout per le conversioni lunghe, download in streaming direttamente su disco e una gerarchia di errori coerente, così puoi intercettare per classe di eccezione senza analizzare i codici di stato.

Come gestisce l'SDK le conversioni che superano il timeout del reverse-proxy?#

L'SDK genera un job_id lato client, lo invia con la richiesta e ripiega sul polling di GET /v1/convert/status/{job_id} se la richiesta originale restituisce 5xx. Restituisce il risultato appena il job risulta riuscito e solleva un errore se il job risulta fallito.

Posso combinare chiamate SDK e richieste HTTP grezze?#

Sì. Ogni SDK chiama gli stessi endpoint REST pubblici documentati in questo sito, quindi le chiamate SDK e quelle HTTP scritte a mano possono condividere un solo progetto e una sola chiave.

Gli SDK coprono gli endpoint di web intelligence V2?#

Sì. Tutti e dieci espongono un namespace V2 che copre perceive, discover, lookup, distill, ingest e watch, accanto ai metodi di conversione file. Consulta la V1 e V2 per capire cosa fa ciascun endpoint.

Che tipo di chiave API serve a un SDK?#

Una chiave API privata (sk_...), generata dalla dashboard e passata al costruttore. Leggila da una variabile d'ambiente invece di scriverla hardcoded, e non includerla mai nel codice lato client. Il codice del browser dovrebbe invece usare una chiave pubblica con un JWT.

Esiste un SDK per il mio linguaggio se non è nell'elenco?#

Non ancora, e non ti serve. L'API è REST puro con body JSON e multipart, quindi qualsiasi client HTTP va bene. Parti dalla panoramica degli endpoint e dalla guida all'autenticazione.