---
seo_title: API de HEIC a WebP: Convertir Imágenes HEIC a WebP | EnConvert
meta_desc: Convierte HEIC a WebP mediante POST /v1/convert/heic-to-webp. Canal alfa conservado, salida de máxima calidad, bytes WebP brutos o una URL de descarga prefirmada.
keywords: api heic a webp, convertir heic a webp, conversor de heic a webp, api heif a webp, api rest heic a webp, convertir heic a webp por programación, heic a webp con canal alfa
---

# API de HEIC a WebP

Convierte HEIC a WebP con el endpoint `POST /v1/convert/heic-to-webp`, que convierte una imagen HEIC/HEIF a un archivo WebP de alta calidad. Si el HEIC tiene canal alfa, se conserva en la salida WebP. Las respuestas devuelven bytes WebP brutos de forma predeterminada, o metadatos JSON con una URL de descarga prefirmada cuando `direct_download=false`.

---

## Endpoint

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

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

**Entrada aceptada:** archivos `.heic or .heif`

**Formato de salida:** `.webp` (`image/webp`)

---

## Autenticación

Requiere una clave de API privada o un token JWT de una clave pública.

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

O:

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

---

## Parámetros de la solicitud

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|----------|---------|-------------|
| `file` | file | Sí | -- | El archivo de imagen `.heic or .heif` que se va a convertir. |
| `output_filename` | `string` | No | Nombre del archivo de entrada | Nombre de archivo de salida personalizado. La extensión `.webp` se añade automáticamente. |
| `direct_download` | `boolean` | No | `true` | Cuando es `true`, devuelve los bytes brutos de la imagen. Cuando es `false`, devuelve metadatos JSON con una URL de descarga prefirmada. |

---

## Detalles de la conversión

- Usa **pillow-heif** para la decodificación HEIC y **Pillow** para la codificación WebP
- Si el HEIC tiene canal alfa, se conserva en la salida WebP
- La calidad de salida se fija al máximo (100)
- WebP normalmente logra tamaños de archivo más pequeños que JPEG con una calidad equivalente


---

## Respuesta

### Descarga directa (`direct_download=true`, predeterminado)

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

Devuelve los bytes brutos de la imagen.

### Respuesta con metadatos (`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
}
```

---

## Ejemplos de código

### 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)
```

---

## Respuestas de error

| Estado | Condición |
|--------|-----------|
| `400 Bad Request` | El archivo no es un archivo `.heic or .heif` |
| `400 Bad Request` | La conversión de la imagen falló (archivo dañado o no compatible) |
| `401 Unauthorized` | Falta la clave de API/token JWT o no es válido |
| `402 Payment Required` | Se agotó la cuota mensual de ops |
| `402 Payment Required` | Se alcanzó el límite de almacenamiento |
| `413 Payload Too Large` | El archivo supera el tamaño máximo permitido por el plan |

---

## Límites

| Límite | Valor |
|-------|-------|
| Tamaño máximo de archivo | Según el plan (Founding: 5 MB) |
| Calidad de salida | Máxima (no configurable) |
| Conversiones mensuales | Según el plan |

---

## Preguntas frecuentes

### ¿Cómo convierto una imagen HEIC a WebP con una API REST?

Envía una solicitud POST `multipart/form-data` a `/v1/convert/heic-to-webp` con el archivo `.heic` o `.heif` en el campo `file`, autenticada mediante `X-API-Key` o un Bearer JWT. La respuesta devuelve bytes WebP brutos de forma predeterminada, o configura `direct_download=false` para recibir JSON con una URL de descarga prefirmada.

### ¿La conversión de HEIC a WebP conserva el canal alfa?

Sí. Si el HEIC tiene canal alfa, se conserva en la salida WebP. La decodificación usa pillow-heif y la codificación usa Pillow.

### ¿Es WebP más pequeño que JPEG para la misma imagen?

WebP normalmente logra tamaños de archivo más pequeños que JPEG con una calidad equivalente. Este endpoint codifica con la máxima calidad (100), que no es configurable.

### ¿Por qué el endpoint de HEIC a WebP devuelve un error 402?

`402 Payment Required` significa que se agotó la cuota mensual de ops o se alcanzó el límite de almacenamiento de tu plan. Los archivos que superan el tamaño máximo de tu plan devuelven `413 Payload Too Large`.