# Sube imágenes a Wix con la API de Media Manager
> Genera los tamaños exactos con SocialCutter y súbelos al Media Manager de Wix por su API, listos para tus páginas y entradas.
- URL: https://socialcutter.theboomer.dev/guias/wix/
- Idioma: es
- Familia: cms
- Actualizado: 2026-09-24
- Palabras clave: Wix, Media Manager, generate-upload-url, API key, subida multipart, imágenes, Node
## 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`:

```bash
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

```bash
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`.

```bash
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

```js
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)](/guias/curl/)
- Node: [Procesa imágenes con la API desde Node](/guias/node/)
- Webflow: [Integra SocialCutter con la API de Webflow](/guias/webflow/)
- WordPress: [Integra SocialCutter con WordPress y WooCommerce](/guias/wordpress/)
- Automatización: [Automatiza el recorte de imágenes para redes sociales](/guias/automatizar-imagenes-redes-sociales/)
- Documentación: https://docs.socialcutter.theboomer.dev