Procesa imágenes con la API desde la terminal (curl)

Antes de empezar

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

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

# 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

# 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

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

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.

# 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

# 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.

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
• Documentación de la API: https://docs.socialcutter.theboomer.dev
• Dashboard: https://dash.socialcutter.theboomer.dev