# Procesa imágenes con la API desde la terminal (curl)
> Guia practica de la API de SocialCutter con curl: salud, credenciales, plataformas, procesado por URL y por fichero, historial, monedero y errores tipicos.
- URL: https://socialcutter.theboomer.dev/guias/curl/
- Idioma: es
- Familia: api
- Actualizado: 2026-09-24
- Palabras clave: curl, API, SocialCutter, terminal, jq, procesar imagenes, API key
## Antes de empezar

Necesitas `curl` y `jq`. Guarda la base y la clave en variables para no repetirlas:

```bash
export API_URL="https://api.socialcutter.theboomer.dev"
export API_KEY="sc_tu_clave"
```

La referencia completa está en https://docs.socialcutter.theboomer.dev.

## 1. Obtener la API key

Entra en https://dash.socialcutter.theboomer.dev, abre **Perfil → API keys** y crea una clave. Empieza por `sc_`, se muestra una sola vez y solo puede haber una activa por cuenta. Si creas otra sin revocar la anterior, la API responde 400.

## 2. Comprobar salud y credenciales

```bash
# Salud: endpoint publico, no requiere clave
curl -s "$API_URL/api/v1/health" | jq

# Identidad de la cuenta que usa la clave
curl -s "$API_URL/api/v1/auth/me" -H "X-API-Key: $API_KEY" | jq

# Usos disponibles
curl -s "$API_URL/api/v1/credits" -H "X-API-Key: $API_KEY" | jq
```

`/api/v1/health` devuelve el estado del servicio, la versión, el uptime y la conexión con la base de datos. `/api/v1/auth/me` confirma qué cuenta está usando la clave. Si esta llamada devuelve 401, la clave está mal o revocada.

## 3. Listar plataformas, formatos y modos

```bash
# Forma de la respuesta: primero las claves de nivel superior
curl -s "$API_URL/api/v1/platforms" | jq 'keys'

# Todas las plataformas con sus formatos, medidas y relacion de aspecto
curl -s "$API_URL/api/v1/platforms" | jq

# Formatos de salida y modos de ajuste
curl -s "$API_URL/api/v1/formats" | jq
curl -s "$API_URL/api/v1/fit-modes" | jq
```

`/platforms`, `/formats` y `/fit-modes` son públicos. Empieza por `jq 'keys'` para ver la forma real de la respuesta y después recórrela con la ruta que necesites.

Estas son las combinaciones que acepta `destinations`:

| Plataforma | Formato | Medidas | Relación |
|---|---|---|---|
| instagram | post | 1080x1080 | 1:1 |
| instagram | story | 1080x1920 | 9:16 |
| instagram | landscape | 1080x566 | 1.91:1 |
| facebook | post | 1200x630 | 1.91:1 |
| facebook | story | 1080x1920 | 9:16 |
| facebook | cover | 820x312 | 2.63:1 |
| twitter | post | 1200x675 | 16:9 |
| twitter | header | 1500x500 | 3:1 |
| linkedin | post | 1200x627 | 1.91:1 |
| linkedin | cover | 1128x191 | 5.9:1 |
| youtube | thumbnail | 1280x720 | 16:9 |
| youtube | banner | 2560x1440 | 16:9 |
| tiktok | cover | 1080x1920 | 9:16 |

## 4. Procesar una imagen por URL

```bash
curl -s -X POST "$API_URL/api/v1/images/process" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-001" \
  -d '{
    "source": { "type": "url", "value": "https://example.com/foto.jpg" },
    "destinations": [
      { "platform": "instagram", "format": "post" },
      { "platform": "tiktok", "format": "cover" }
    ]
  }' | jq
```

El campo `source` indica de dónde viene la imagen (`url` o base64) y `destinations` es la lista de plataforma y formato que quieres. La cabecera `Idempotency-Key` hace seguros los reintentos; sin ella la API genera una clave aleatoria por petición.

## 5. Procesar un fichero local

```bash
curl -s -X POST "$API_URL/api/v1/images/process/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@./foto.jpg" \
  -F 'destinations=[{"platform":"linkedin","format":"post"},{"platform":"youtube","format":"thumbnail"}]' | jq
```

En multipart el fichero va en `file` y `destinations` como una cadena JSON en un campo del formulario. El límite es 5 MB; por encima la API responde 413.

### Alternativa en base64

`POST /api/v1/images/upload` acepta la imagen como cadena base64 en el cuerpo JSON, sin fichero ni URL de origen. Úsalo solo cuando la imagen no tenga una URL pública accesible.

## 6. Leer la respuesta y descargar un resultado

La respuesta trae `image_id` y una lista `outputs`, una por destino, con la URL del resultado, la plataforma, el formato y las medidas.

```bash
# Guarda la respuesta en un fichero
curl -s -X POST "$API_URL/api/v1/images/process" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "url", "value": "https://example.com/foto.jpg" },
    "destinations": [{ "platform": "instagram", "format": "post" }]
  }' > out.json

# Id, plataforma y formato de cada salida
jq '.image_id, (.outputs[] | {url, platform, format})' out.json

# Descarga el primer resultado
curl -s -o resultado.webp "$(jq -r '.outputs[0].url' out.json)"
```

Si alguna clave de medidas no aparece, imprime el objeto completo con `jq '.outputs[0]'` para ver su forma real.

## 7. Historial y monedero

```bash
# Ultimas 10 imagenes
curl -s "$API_URL/api/v1/history?limit=10" -H "X-API-Key: $API_KEY" | jq

# Solo las creadas desde la API
curl -s "$API_URL/api/v1/history?origin=api&limit=10" -H "X-API-Key: $API_KEY" | jq

# Monedero: cuota diaria, usada, restante, bolsa extra y saldo comprado
curl -s "$API_URL/api/v1/wallet" -H "X-API-Key: $API_KEY" | jq
```

`limit` admite de 1 a 100 (por defecto 50) y `skip` sirve para paginar. El filtro `origin` distingue `browser` (dashboard) de `api`.

## 8. Elegir el modo de ajuste

`fit_mode` controla cómo encaja la imagen en cada formato:

| Modo | Comportamiento |
|---|---|
| `cover` | Escala y recorta el exceso de forma centrada. Es el valor por defecto. |
| `contain` | Encaja la imagen completa y rellena con `background_color`. |
| `fill` | Estira la imagen. |
| `stretch` | Fuerza las dimensiones exactas. |

```bash
curl -s -X POST "$API_URL/api/v1/images/process" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "url", "value": "https://example.com/foto.jpg" },
    "destinations": [{ "platform": "facebook", "format": "cover" }],
    "options": { "fit_mode": "contain", "format": "webp", "quality": 85 }
  }' | jq
```

El recorte de `cover` es centrado. En `options` también puedes fijar `format` (webp, png, jpg, gif) y `quality` (1 a 100, por defecto 85).

## Reintentos, lotes y paginación

- Reutiliza la misma cabecera `Idempotency-Key` cuando reintentes una petición: la API no la procesa dos veces.
- `POST /api/v1/images/batch` procesa varias imágenes en una sola llamada y devuelve el resultado por índice. Los elementos fallidos se devuelven.
- `GET /api/v1/history` pagina con `limit` (de 1 a 100) y `skip`.
- Cada respuesta incluye la cabecera `X-Tentpole-Version` con la versión en ejecución.

## Coste

- 1 uso por destino (plataforma y formato) por petición.
- Destinos repetidos en la misma petición no se cobran dos veces.
- Los procesamientos fallidos se devuelven.

## Errores típicos

| Código | Significado |
|---|---|
| 400 | Payload inválido: plataforma, formato o modo desconocido, JSON mal formado, o clave ya activa |
| 401 | Credenciales ausentes, mal formadas, caducadas o revocadas |
| 404 | Recurso no encontrado (id de imagen o de fichero) |
| 413 | El fichero supera 5 MB |
| 422 | Error de validación de la petición |
| 429 | Cuota del monedero agotada |
| 500 | Fallo de procesamiento; los usos de esa petición se devuelven |

## Siguientes pasos

- Guía de MCP: [Usa SocialCutter desde tu LLM o editor con MCP](/guias/mcp/)
- Documentación de la API: https://docs.socialcutter.theboomer.dev
- Dashboard: https://dash.socialcutter.theboomer.dev