Sube imágenes a Wix con la API de Media Manager

Por qué generar las medidas antes de subir

Wix muestra cada imagen recortándola al hueco donde va: la cabecera de la página, la ficha de un producto, la miniatura de la galería, la entrada del blog en el feed. Si subes el maestro, dejas ese recorte a criterio del editor y el resultado cambia entre vistas.

El flujo bueno es: entra un maestro, SocialCutter devuelve cada medida y Wix recibe el fichero ya recortado. El recorte de cover, el modo por defecto, es centrado: escala y recorta el sobrante a partes iguales por los dos lados. No hay detección de sujeto ni análisis de contenido, así que deja aire alrededor del motivo.

Dónde va en el sitio	Destino SocialCutter	Medida
Imagen principal de producto	instagram post	1080x1080 (1:1)
Imagen vertical o story	instagram story	1080x1920 (9:16)
Cabecera de página o sección	twitter header	1500x500 (3:1)
Banner ancho	facebook post	1200x630 (1.91:1)
Miniatura de vídeo	youtube thumbnail	1280x720 (16:9)

Las medidas y los formatos reales salen de GET /api/v1/platforms, que es público. El catálogo no incluye 4:5: lo cuadrado es 1:1 y lo vertical es 9:16.

Antes de empezar: API key y permisos

La API key se genera en el dashboard de Wix y se envía en la cabecera Authorization tal cual, sin la palabra Bearer:

export WIX_AUTH="IST.eyJra..."   # API key del dashboard
export SC_KEY="sc_tu_clave"

Para el Media Manager la key necesita el permiso Manage Media Manager. La documentación del flujo está en:

• Generar la URL de subida: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/generate-file-upload-url
• Subir con esa URL: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/upload-api

Aviso: las APIs de Wix están versionadas y los nombres de parámetros cambian. Contrasta siempre contra la documentación del momento antes de dar un flujo por bueno.

1. Genera los tamaños con SocialCutter

curl -s -X POST "https://api.socialcutter.theboomer.dev/api/v1/images/process" \
  -H "X-API-Key: *** \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wix-home-2026-09" \
  -d '{
    "source": { "type": "url", "value": "https://tu-cdn.com/maestro.jpg" },
    "destinations": [
      { "platform": "instagram", "format": "post" },
      { "platform": "twitter", "format": "header" }
    ]
  }' > sc.json

jq -r '.outputs[] | "\(.platform)/\(.format) \(.width)x\(.height) \(.url)"' sc.json

Cada salida trae url, width, height y size_bytes. Con un fichero local usa POST /api/v1/images/process/upload (multipart, campo file, máximo 5 MB); para varios maestros, POST /api/v1/images/batch.

2. Pide la URL de subida y sube el binario

El Media Manager no acepta el fichero directamente contra su endpoint: primero se pide una URL firmada y se sube ahí con PUT.

WIX_BASE="https://www.wixapis.com"

# 2a. URL firmada
UPLOAD_URL=$(curl -s -X POST "$WIX_BASE/site-media/v1/files/generate-upload-url" \
  -H "Authorization: $WIX_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"mimeType":"image/jpeg","fileName":"categoria.jpg"}' | jq -r '.uploadUrl')

# 2b. Subir el fichero (binario)
curl -s -X PUT "$UPLOAD_URL?filename=categoria.jpg" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@categoria.jpg" | jq '.file | {id, url, displayName}'

La respuesta trae file.id y file.url (un static.wixstatic.com/media/...). Esa url es la que pegas en el elemento de la página, en la ficha de producto o en la entrada.

Si tus salidas ya están en una URL pública, te ahorras la subida: POST /site-media/v1/files/import con {"url": ..., "mimeType": ...} las trae directamente, y POST /site-media/v1/bulk/files/import-v2 importa varias de una vez.

3. Snippet Node

const WIX = 'https://www.wixapis.com'
const AUTH = process.env.WIX_AUTH // API key, sin 'Bearer'
const SC_KEY = process.env.SC_KEY

async function subir(urlSocialCutter, nombre) {
  // 1. URL firmada
  const r1 = await fetch(`${WIX}/site-media/v1/files/generate-upload-url`, {
    method: 'POST',
    headers: { Authorization: AUTH, 'Content-Type': 'application/json' },
    body: JSON.stringify({ mimeType: 'image/jpeg', fileName: nombre })
  })
  const { uploadUrl } = await r1.json()

  // 2. Subir el binario
  const bin = await fetch(urlSocialCutter)
  const r2 = await fetch(`${uploadUrl}?filename=${encodeURIComponent(nombre)}`, {
    method: 'PUT',
    headers: { 'Content-Type': 'image/jpeg' },
    body: Buffer.from(await bin.arrayBuffer())
  })
  const { file } = await r2.json()
  return file // { id, url, ... } — todavía puede no estar listo
}

;(async () => {
  const sc = await fetch('https://api.socialcutter.theboomer.dev/api/v1/images/process', {
    method: 'POST',
    headers: { 'X-API-Key': SC_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      source: { type: 'url', value: 'https://tu-cdn.com/maestro.jpg' },
      destinations: [{ platform: 'instagram', format: 'post' }]
    })
  }).then(r => r.json())

  for (const out of sc.outputs) {
    const f = await subir(out.url, `wix-${out.platform}-${out.format}.jpg`)
    console.log(out.platform, out.format, '→', f.url)
  }
})()

Límites reales de la API de Wix

Conviene tenerlos claros antes de prometer una automatización:

• El Media Manager sí es accesible con API key y el permiso correcto, para subir e importar ficheros.
• El fichero no está listo al responder. Un 200 en la subida no significa que puedas usarlo: la documentación pide esperar al evento File Ready (o al File Failed) antes de gestionarlo.
• Los ficheros de más de 10 MB se suben con la URL resumible (generate-resumable-upload-url), no con la normal.
• Publicar contenido por API no está disponible en todos los planes ni editores. La Blog API existe, pero llamarla exige autenticarte como app o usuario de Wix con los permisos correspondientes y, para una app de terceros, indicar un memberId como autor. En muchos sitios lo más práctico es subir la imagen al Media Manager y colocarla en el editor, o exponer un web method de Velo dentro del propio sitio, que se ejecuta con los permisos del sitio. Referencia: https://dev.wix.com/docs/api-reference/business-solutions/blog/introduction

Por eso esta guía cubre la parte que sí es programable —las imágenes— y deja la publicación a la vía que permita tu plan.

Coste

• 1 uso por destino (plataforma y formato) por petición; los repetidos no se cobran dos veces.
• Los procesamientos fallidos se devuelven.
• Todos los planes incluyen API y MCP: Free 3 usos/día, Basic 10, Pro 30, Agency 100, desde 0 / 3 / 9 / 29 EUR al mes.

Errores típicos

Síntoma	Causa	Solución
401 en la API de Wix	Key mal copiada o Bearer de más	Manda solo la key en Authorization
403 al generar la URL	Falta el permiso Manage Media Manager	Recrea la key con ese permiso
La subida responde pero la imagen no aparece	El fichero aún no está listo	Espera al evento File Ready antes de usarla
Content-Type incorrecto	Se sube sin cabecera o con el mime equivocado	Manda image/jpeg o image/png acorde al fichero
La imagen se ve recortada rara	Subiste el maestro y Wix lo ha recortado	Sube ya la medida de SocialCutter
413 en SocialCutter	El maestro supera 5 MB	Reduce la imagen antes de subirla
429 en SocialCutter	Cuota del monedero agotada	Consulta tu cuota en el dashboard o sube de plan

Siguientes pasos

• Terminal: Procesa imágenes con la API desde la terminal (curl)
• Node: Procesa imágenes con la API desde Node
• Webflow: Integra SocialCutter con la API de Webflow
• WordPress: Integra SocialCutter con WordPress y WooCommerce
• Automatización: Automatiza el recorte de imágenes para redes sociales
• Documentación: https://docs.socialcutter.theboomer.dev