API di Conversione Pagine Web#
Gli endpoint delle pagine web renderizzano URL live in un browser reale e li convertono in PDF, screenshot PNG a pagina intera, o Markdown pulito in formato GitHub-Flavored. Gli endpoint a URL singolo vengono eseguiti in modo sincrono (o asincrono in batch), mentre gli endpoint website scansionano un intero sito (tramite parsing della sitemap o una scansione completa in ampiezza) e raggruppano ogni pagina in un unico archivio ZIP. Tutti gli endpoint condividono la stessa pipeline del browser: chiusura dei banner dei cookie, scroll per il lazy-load, gestione degli header sticky, e supporto per pagine protette da HTTP Basic Auth, cookie iniettati o header personalizzati.
Conversioni supportate#
| Conversione | Endpoint | Descrizione |
|---|---|---|
| URL in PDF | POST /v1/convert/url-to-pdf |
Converte qualsiasi URL pubblicamente accessibile in un PDF ad alta fedeltà, con output a pagina singola continua o paginato, dimensioni di pagina personalizzate, intestazioni/piè di pagina e modalità batch asincrona. |
| URL in Screenshot | POST /v1/convert/url-to-screenshot |
Cattura uno screenshot a pagina intera di qualsiasi URL come PNG ad alta fedeltà, ridimensionando il viewport all'altezza reale del contenuto in modo che l'intera pagina sia in un'unica immagine. |
| URL in Markdown | POST /v1/convert/url-to-markdown |
Converte una pagina web in Markdown pulito in formato GitHub-Flavored con frontmatter YAML, usando l'estrazione Readability per rimuovere il boilerplate. È pensato per pipeline di ingestione LLM e RAG. |
| Website in PDF | POST /v1/convert/website-to-pdf |
Scansiona un intero sito web tramite sitemap o scansione completa in ampiezza, converte ogni pagina individuata in PDF e raggruppa i risultati in un unico archivio ZIP. |
| Website in Screenshot | POST /v1/convert/website-to-screenshot |
Individua ogni pagina di un sito web tramite sitemap o scansione completa e cattura un PNG a pagina intera di ciascuna, consegnati come un unico archivio ZIP. |
Convenzioni condivise#
- Autenticazione: ogni endpoint accetta una chiave privata nell'header
X-API-Key; i tre endpoint a URL singolo accettano anche token JWT Bearer a chiave pubblica (limitati a un singolo URL, modalità sincrona e download diretto), mentre gli endpoint website richiedono una chiave privata. Consulta Autenticazione. - Sincrono vs asincrono: gli endpoint a URL singolo vengono eseguiti in modo sincrono per impostazione predefinita e passano ad asincrono (
async_mode=true, HTTP 202 con unbatch_id) per i batch; gli endpoint website sono sempre asincroni. Esegui il polling diGET /v1/convert/batch/{batch_id}per i risultati. Consulta Job sync e async. - Risposte: le conversioni completate restituiscono un URL di download presigned e
object_key; gli endpoint a URL singolo possono invece restituire i byte grezzi dell'output condirect_download=true. - Parametri del browser e del rendering:
viewport_width/viewport_height,handle_cookies,enable_scroll,load_media,wait_for_imagesehandle_sticky_headersono condivisi su tutti e cinque gli endpoint, così come le opzioniauth,cookies(max 50) eheaders(max 20) per le pagine protette. Consulta Job sync e async. - Errori e limitazioni di piano: tutti gli endpoint usano gli stessi codici di stato:
400per input non valido,401per credenziali errate,402per limiti di quota o storage, e403per funzionalità limitate dal piano (async, webhook, output ZIP, basic auth, cattura di siti web). Consulta Codici di Errore.
Domande frequenti#
Quale endpoint dovrei usare per una singola pagina rispetto a un intero sito web?#
Usa url-to-pdf, url-to-screenshot o url-to-markdown per un singolo URL o un elenco esplicito di URL. Usa website-to-pdf o website-to-screenshot quando vuoi che sia l'API a individuare le pagine tramite parsing di sitemap.xml o una scansione completa in ampiezza e a restituire tutto come un unico ZIP.
Questi endpoint possono convertire pagine protette da login?#
Sì, sui piani con accesso al basic auth. Tutti e cinque gli endpoint accettano un oggetto auth per l'HTTP Basic Auth, fino a 50 cookies iniettati per l'accesso basato su sessione, e fino a 20 headers personalizzati. Queste opzioni sono utili per siti di staging, pagine riservate ai membri e dashboard.
Come ottengo il risultato di un job asincrono?#
I job asincroni restituiscono immediatamente HTTP 202 con un batch_id. Esegui il polling di GET /v1/convert/batch/{batch_id} con la tua chiave privata per gli stati per-URL e gli URL di download presigned, fornisci un callback_url per ricevere un POST webhook al completamento, oppure affidati all'email di completamento inviata a notification_email (il proprietario del progetto per impostazione predefinita).