API Documentation

API di Conversione Immagini#

Un'unica API REST converte immagini tra JPEG, PNG, WebP, HEIC e SVG, trasforma pagine PDF in JPEG e comprime le immagini mantenendone il formato. Ogni endpoint accetta un caricamento multipart/form-data e converte in modo sincrono usando Pillow, CairoSVG, pillow-heif o PyMuPDF a seconda della coppia di formati. Per impostazione predefinita la risposta è il file convertito grezzo; imposta direct_download=false per ricevere invece metadati JSON con un URL di download prefirmato.

Conversioni supportate#

Conversione Endpoint Descrizione
Da JPEG a PNG POST /v1/convert/jpeg-to-png Converte un file .jpeg/.jpg caricato in un PNG lossless con piena fedeltà cromatica.
Da PNG a JPEG POST /v1/convert/png-to-jpeg Converte un .png in un JPEG alla massima qualità, compositando le aree trasparenti su uno sfondo bianco.
Da JPEG a SVG POST /v1/convert/jpeg-to-svg Incorpora il JPEG in base64 come data URI all'interno di un elemento SVG <image>. È un wrapper raster, non una vettorizzazione.
Da SVG a JPEG POST /v1/convert/svg-to-jpeg Rasterizza l'SVG con CairoSVG e restituisce un JPEG, compositando la trasparenza su uno sfondo bianco.
Da JPEG a HEIC POST /v1/convert/jpeg-to-heic Codifica un file .jpeg/.jpg caricato in un file HEIC di alta qualità usando il codec HEIF.
Da HEIC a JPEG POST /v1/convert/heic-to-jpeg Decodifica un file .heic o .heif caricato (ad es. foto iPhone) e produce un JPEG di alta qualità.
Da JPEG a WebP POST /v1/convert/jpeg-to-webp Produce un WebP di alta qualità con una dimensione file inferiore rispetto al JPEG equivalente, per la distribuzione web.
Da WebP a JPEG POST /v1/convert/webp-to-jpeg Converte un .webp in JPEG, compositando eventuali aree trasparenti su uno sfondo bianco.
Da PNG a SVG POST /v1/convert/png-to-svg Incorpora il PNG come data URI base64 in un wrapper SVG che corrisponde alle dimensioni in pixel dell'immagine. Non è vettorizzazione.
Da SVG a PNG POST /v1/convert/svg-to-png Rasterizza l'SVG con CairoSVG alla sua dimensione dichiarata, preservando la trasparenza nel PNG di output.
Da PNG a HEIC POST /v1/convert/png-to-heic Converte un .png in HEIC, compositando le aree trasparenti su uno sfondo bianco.
Da HEIC a PNG POST /v1/convert/heic-to-png Converte un file .heic o .heif caricato in un PNG lossless con piena fedeltà cromatica.
Da PNG a WebP POST /v1/convert/png-to-webp Converte un .png in WebP mantenendo il canale alfa (trasparenza).
Da WebP a PNG POST /v1/convert/webp-to-png Converte un .webp in un PNG lossless mantenendo la trasparenza.
Da SVG a HEIC POST /v1/convert/svg-to-heic Renderizza l'SVG con CairoSVG e lo codifica come HEIC alla massima qualità su uno sfondo bianco.
Da HEIC a SVG POST /v1/convert/heic-to-svg Decodifica l'HEIC in PNG e lo incorpora come data URI base64 in un wrapper SVG. Non è vettorizzazione.
Da SVG a WebP POST /v1/convert/svg-to-webp Renderizza l'SVG con CairoSVG e lo codifica come WebP alla massima qualità mantenendo la trasparenza.
Da WebP a SVG POST /v1/convert/webp-to-svg Decodifica il WebP in PNG e lo incorpora come data URI base64 in un wrapper SVG. Non è vettorizzazione.
Da HEIC a WebP POST /v1/convert/heic-to-webp Converte un file .heic o .heif caricato in un WebP di alta qualità, mantenendo il canale alfa se presente.
Da WebP a HEIC POST /v1/convert/webp-to-heic Converte un .webp in HEIC alla massima qualità, compositando la trasparenza su uno sfondo bianco.
Da PDF a JPEG POST /v1/convert/pdf-to-jpeg Renderizza ogni pagina PDF come JPEG a 144 DPI; i PDF a pagina singola restituiscono un JPEG, i PDF multipagina restituiscono uno ZIP con un JPEG per pagina.
Comprimi immagine POST /v1/convert/compress-image Comprime PNG, JPEG o WebP mantenendo il formato (invariato): ottimizzazione prima di tutto lossless, con downscaling opzionale a proporzioni bloccate fino a un budget target_size_kb.

Convenzioni comuni#

  • Autenticazione: ogni endpoint richiede una chiave API privata (X-API-Key: sk_...) oppure un token JWT da chiave pubblica (Authorization: Bearer <jwt_token>). Vedi Autenticazione.
  • Forma della richiesta: tutti gli endpoint accettano multipart/form-data con un campo file obbligatorio più i parametri opzionali output_filename e direct_download. Gli endpoint di rasterizzazione SVG (svg-to-png, svg-to-jpeg, svg-to-webp) accettano anche le dimensioni opzionali in pixel width/height, e compress-image accetta un budget opzionale target_size_kb. Vedi Job sync e async.
  • Risposte: le conversioni vengono eseguite in modo sincrono. Con direct_download=true (il valore predefinito) ottieni i byte grezzi convertiti; con direct_download=false ottieni metadati JSON che includono presigned_url, object_key, filename, file_size e conversion_time_seconds.
  • Errori e limiti: gli endpoint restituiscono 400 per input non valido o corrotto, 401 per credenziali mancanti/non valide, 402 quando la quota mensile di ops è esaurita o viene raggiunto il limite di storage del tuo piano, e 413 quando un file supera la dimensione massima consentita dal tuo piano. Vedi Codici di errore.
  • Qualità: gli endpoint di conversione codificano alla massima qualità (non configurabile). La dimensione dell'output è invece configurabile dove indicato sopra: width/height sugli endpoint di rasterizzazione SVG, target_size_kb su compress-image.

Domande frequenti#

Come converto un formato immagine con una REST API?#

Invia una richiesta POST multipart/form-data all'endpoint corrispondente /v1/convert/{source}-to-{target} con la tua immagine nel campo file, autenticandoti tramite X-API-Key o un token JWT Bearer. Per impostazione predefinita l'API risponde con il file convertito grezzo; imposta direct_download=false per ottenere invece metadati JSON con un URL di download prefirmato.

Gli endpoint di output SVG vettorizzano la mia immagine?#

No. Gli endpoint da JPEG, PNG, WebP e HEIC a SVG codificano in base64 l'immagine raster e la incorporano come data URI all'interno di un elemento SVG <image> dimensionato secondo le dimensioni in pixel originali. Non tracciano l'immagine in percorsi vettoriali, e la codifica base64 aggiunge circa il 33% alla dimensione del file.

Cosa succede alla trasparenza durante la conversione?#

Dipende dal formato di output. Le conversioni verso JPEG e HEIC compositano le aree trasparenti su uno sfondo bianco, perché questi output vengono prodotti senza trasparenza. Le conversioni verso PNG e WebP mantengono il canale alfa.

← markdown-to-html jpeg-to-png →