HTML in Immagine

Cattura un URL di una pagina web o contenuto HTML grezzo come immagine screenshot. Supporta l'emulazione dei dispositivi (desktop, tablet, mobile), la cattura dell'intera pagina e più formati di output.

Endpoint API

POST /api/v1/tools/image/html-to-image

Accetta un corpo JSON (non multipart). Non è necessario alcun caricamento di file.

Parametri

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
url	string	Condizionale	-	URL da catturare (deve essere un URL valido)
html	string	Condizionale	-	Contenuto HTML grezzo da renderizzare (da 1 a 5.000.000 caratteri)
format	string	No	"png"	Formato di output: jpg, png, webp
quality	number	No	90	Qualità dell'output per formati con perdita (da 1 a 100)
fullPage	boolean	No	false	Cattura l'intera pagina scorrevole, non solo il viewport
devicePreset	string	No	"desktop"	Emulazione del dispositivo: desktop, tablet, mobile, custom
viewportWidth	number	No	1280	Larghezza personalizzata del viewport in pixel (da 320 a 3840, usata quando devicePreset è custom)
viewportHeight	number	No	720	Altezza personalizzata del viewport in pixel (da 320 a 2160, usata quando devicePreset è custom)

Deve essere fornito url oppure html, ma non entrambi.

Preset dei Dispositivi

Preset	Larghezza	Altezza	UA Mobile
desktop	1280	720	No
tablet	768	1024	No
mobile	375	812	Sì
custom	(specificato dall'utente)	(specificato dall'utente)	No

Richiesta di Esempio

Cattura una pagina web:

curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "png", "fullPage": true, "devicePreset": "desktop"}'

Renderizza contenuto HTML:

curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<div style=\"padding: 20px; background: #f0f0f0;\"><h1>Hello</h1></div>", "format": "png"}'

Risposta di Esempio

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/screenshot.png",
  "originalSize": 0,
  "processedSize": 145000
}

Note

• Richiede che Chromium sia installato sul server. Restituisce HTTP 503 se il servizio del browser non è disponibile.
• Gli URL vengono validati contro attacchi SSRF (gli indirizzi di rete privati/interni sono bloccati).
• Questo endpoint è soggetto a un limite di 120 richieste all'ora.
• originalSize è sempre 0 poiché questo strumento genera immagini da URL/HTML.
• Il nome file di output è screenshot.<format>.
• Se il caricamento della pagina richiede troppo tempo, la richiesta restituisce HTTP 504 (gateway timeout).
• Se il servizio del browser va in crash ripetutamente, viene temporaneamente disabilitato e restituisce HTTP 503 con codice BROWSER_CRASHED.