---
seo_title: API da HEIC a WebP: Converti immagini HEIC in WebP | EnConvert
meta_desc: Converti HEIC in WebP tramite POST /v1/convert/heic-to-webp. Canale alfa preservato, output a qualità massima, byte WebP grezzi o URL di download presigned.
keywords: convertire heic in webp api, come convertire heic in webp, heic to webp converter api, heif to webp api, heic to webp rest api, convertire heic in webp via api, heic to webp canale alfa
---

# API da HEIC a WebP

Converti HEIC in WebP con l'endpoint `POST /v1/convert/heic-to-webp`, che converte un'immagine HEIC/HEIF in un file WebP di alta qualità. Se l'HEIC ha un canale alfa, viene preservato nell'output WebP. Le risposte restituiscono byte WebP grezzi per impostazione predefinita, oppure metadati JSON con un URL di download presigned quando `direct_download=false`.

---

## Endpoint

```
POST /v1/convert/heic-to-webp
```

**Content-Type:** `multipart/form-data`

**Input accettato:** file `.heic or .heif`

**Formato di output:** `.webp` (`image/webp`)

---

## Autenticazione

Richiede una chiave API privata oppure un token JWT generato da una chiave pubblica.

```
X-API-Key: sk_your_private_key
```

Oppure:

```
Authorization: Bearer <jwt_token>
```

---

## Parametri della richiesta

| Parametro | Tipo | Obbligatorio | Predefinito | Descrizione |
|-----------|------|----------|---------|-------------|
| `file` | file | Sì | -- | Il file immagine `.heic or .heif` da convertire. |
| `output_filename` | `string` | No | Nome del file di input | Nome file di output personalizzato. L'estensione `.webp` viene aggiunta automaticamente. |
| `direct_download` | `boolean` | No | `true` | Se `true`, restituisce i byte grezzi dell'immagine. Se `false`, restituisce metadati JSON con un URL di download presigned. |

---

## Dettagli della conversione

- Usa **pillow-heif** per la decodifica HEIC e **Pillow** per la codifica WebP
- Se l'HEIC ha un canale alfa, viene preservato nell'output WebP
- La qualità di output è impostata al massimo (100)
- WebP raggiunge tipicamente dimensioni di file inferiori rispetto a JPEG a parità di qualità


---

## Risposta

### Download diretto (`direct_download=true`, predefinito)

```
HTTP 200 OK
Content-Type: image/webp
Content-Disposition: inline; filename="photo_20260405_123456789.webp"
```

Restituisce i byte grezzi dell'immagine.

### Risposta con metadati (`direct_download=false`)

```json
{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/heic-to-webp/photo_20260405_123456789.webp",
    "filename": "photo_20260405_123456789.webp",
    "file_size": 45678,
    "conversion_time_seconds": 0.5
}
```

---

## Esempi di codice

### Python

```python
import requests

with open("photo.heic", "rb") as f:
    response = requests.post(
        "https://api.enconvert.com/v1/convert/heic-to-webp",
        headers={"X-API-Key": "sk_your_private_key"},
        files={"file": ("photo.heic", f)}
    )

with open("photo_20260405_123456789.webp", "wb") as out:
    out.write(response.content)
```

### Node.js

```javascript
const form = new FormData();
form.append("file", fs.createReadStream("photo.heic"));

const response = await fetch("https://api.enconvert.com/v1/convert/heic-to-webp", {
    method: "POST",
    headers: { "X-API-Key": "sk_your_private_key" },
    body: form
});

fs.writeFileSync("photo_20260405_123456789.webp", Buffer.from(await response.arrayBuffer()));
```

### PHP

```php
$ch = curl_init("https://api.enconvert.com/v1/convert/heic-to-webp");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: sk_your_private_key"],
    CURLOPT_POSTFIELDS => ["file" => new CURLFile("photo.heic")]
]);
$output = curl_exec($ch);
curl_close($ch);
file_put_contents("photo_20260405_123456789.webp", $output);
```

### Go

```go
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("file", "photo.heic")
file, _ := os.Open("photo.heic")
io.Copy(part, file)
writer.Close()

req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/heic-to-webp", body)
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("X-API-Key", "sk_your_private_key")
resp, _ := http.DefaultClient.Do(req)
```

---

## Risposte di errore

| Stato | Condizione |
|--------|-----------|
| `400 Bad Request` | Il file non è un file `.heic or .heif` |
| `400 Bad Request` | Conversione dell'immagine non riuscita (file corrotto o non supportato) |
| `401 Unauthorized` | Chiave API / token JWT mancante o non valido |
| `402 Payment Required` | Quota mensile di ops esaurita |
| `402 Payment Required` | Limite di storage raggiunto |
| `413 Payload Too Large` | Il file supera la dimensione massima consentita dal piano |

---

## Limiti

| Limite | Valore |
|-------|-------|
| Dimensione massima del file | Dipende dal piano (Founding: 5 MB) |
| Qualità di output | Massima (non configurabile) |
| Conversioni mensili | Dipende dal piano |

---

## Domande frequenti

### Come converto un'immagine HEIC in WebP con una API REST?

Invia una richiesta POST `multipart/form-data` a `/v1/convert/heic-to-webp` con il file `.heic` o `.heif` nel campo `file`, autenticata tramite `X-API-Key` o un JWT Bearer. La risposta restituisce byte WebP grezzi per impostazione predefinita, oppure imposta `direct_download=false` per ricevere JSON con un URL di download presigned.

### La conversione da HEIC a WebP mantiene il canale alfa?

Sì. Se l'HEIC ha un canale alfa, viene preservato nell'output WebP. La decodifica usa pillow-heif e la codifica usa Pillow.

### WebP è più leggero di JPEG per la stessa immagine?

WebP raggiunge tipicamente dimensioni di file inferiori rispetto a JPEG a parità di qualità. Questo endpoint codifica alla qualità massima (100), che non è configurabile.

### Perché l'endpoint da HEIC a WebP restituisce un errore 402?

`402 Payment Required` indica che è stata esaurita la quota mensile di ops o raggiunto il limite di storage del tuo piano. I file che superano la dimensione massima del piano restituiscono invece `413 Payload Too Large`.