Widget Insertable

Añade conversión de imágenes a tu sitio web con una sola etiqueta de script.

Inicio rápido

Añade esta etiqueta de script en cualquier parte de tu HTML. El widget se renderiza inmediatamente después de la etiqueta:

<script src="https://koalapic.com/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-mode="all"
        data-theme="auto"></script>

¡Eso es todo! El widget crea su propio contenedor y empieza a funcionar.

Opciones de configuración

Configura el widget mediante atributos data-* en la etiqueta de script u opciones pasadas a KoalaPic.init():

Opción	Atributo de datos	Predeterminado	Descripción
`mode`	`data-mode`	`"all"`	Modo del widget: `convert`, `compress`, `resize` o `all`
`theme`	`data-theme`	`"auto"`	Tema de color: `light`, `dark` o `auto` (sigue el sistema)
`accent_color`	`data-accent-color`	`"#3b82f6"`	Color de acento principal (hex). Ejemplo: `#8b5cf6`
`allowed_formats`	`data-allowed-formats`	`(all)`	Formatos de salida separados por comas: avif, bmp, gif, heic, ico, jpg, pdf, png, svg, tiff, webp
`max_file_size`	`data-max-file-size`	`50`	Tamaño máximo de subida en MB (1–50)
`callback_url`	`data-callback-url`	`(none)`	URL a la que enviar (POST) los resultados de la conversión al finalizar
`hide_branding`	`data-hide-branding`	`false`	Hide "Powered by KoalaPic" footer
`api_key`	`data-api-key`	`(none)`	Clave de API para solicitudes autenticadas con límites de frecuencia más altos
`width`	`data-width`	`"100%"`	Ancho del iframe del widget (cualquier valor CSS)
`height`	`data-height`	`"500px"`	Alto del iframe del widget (se ajusta automáticamente mediante eventos de redimensionado)
`lang`	`data-lang`	`(auto)`	Código de idioma (p. ej. `fr`, `de`, `ar`). Se detecta automáticamente de la página o el navegador si se omite.

Todas las opciones admiten tanto snake_case como camelCase en la API de JavaScript (p. ej. accent_color o accentColor).

API de JavaScript

Para un control total, usa KoalaPic.init() para crear widgets mediante programación:

<div id="converter"></div>
<script src="https://koalapic.com/static/widget/koalapic-widget.js"></script>
<script>
  var iframe = KoalaPic.init('#converter', {
    mode: 'convert',
    theme: 'dark',
    accentColor: '#8b5cf6',
    allowedFormats: ['jpg', 'png', 'webp'],
    maxFileSize: 25,
    apiKey: 'kp_your_key_here'
  });
</script>

Referencia de la API

Método	Descripción
`KoalaPic.init(selector, config)`	Crea un widget dentro de un elemento contenedor. Devuelve el elemento iframe. Acepta una cadena de selector CSS o un elemento DOM.
`KoalaPic.on(event, callback)`	Registra un listener de eventos. Eventos
`KoalaPic.version`	Cadena con la versión de la librería.

Gestión de eventos

Escucha eventos del ciclo de vida de la conversión usando KoalaPic.on():

KoalaPic.on('conversion_completed', function(result) {
  console.log('Conversion ID:', result.id);
  console.log('Download token:', result.download_token);
  console.log('Format:', result.output_format);
  console.log('File size:', result.file_size);
});

KoalaPic.on('conversion_started', function(data) {
  console.log('Conversion started in mode:', data.mode);
});

KoalaPic.on('conversion_failed', function(data) {
  console.error('Conversion failed:', data.error);
});

Tipos de eventos

Evento	Carga útil	Descripción
`conversion_started`	`{ mode }`	Conversión enviada a la API
`conversion_completed`	`{ id, download_token, output_format, file_size }`	La conversión finalizó correctamente
`conversion_failed`	`{ error }`	La conversión o la solicitud a la API ha fallado

También puedes escuchar directamente los eventos postMessage sin procesar:

window.addEventListener('message', function(event) {
  if (event.data.type === 'koalapic:conversion_complete') {
    console.log(event.data.payload);
  }
});

URL de retorno

Establece callback_url para enviar automáticamente (POST) los resultados de la conversión a tu servidor:

<script src="https://koalapic.com/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-callback-url="https://yoursite.com/api/conversion-hook"></script>

Tu endpoint recibe un POST en JSON con el resultado de la conversión:

{
  "id": "abc123",
  "download_token": "token_xyz",
  "output_format": "webp",
  "file_size": 45210
}

Estilo y personalización

El widget se renderiza dentro de un iframe, por lo que no entrará en conflicto con los estilos de tu página. Puedes personalizar el contenedor:

<!-- Fixed-width centered widget -->
<div id="widget" style="max-width: 600px; margin: 0 auto;"></div>
<script src="https://koalapic.com/static/widget/koalapic-widget.js"></script>
<script>
  KoalaPic.init('#widget', {
    width: '100%',
    height: '500px',
    accentColor: '#e11d48',
    theme: 'dark'
  });
</script>

El iframe tiene border-radius: 8px de forma predeterminada. Anúlalo en el elemento iframe devuelto:

var iframe = KoalaPic.init('#widget', { mode: 'compress' });
iframe.style.borderRadius = '16px';
iframe.style.boxShadow = '0 4px 24px rgba(0,0,0,0.1)';

Límite de frecuencia

Para uso en producción, recomendamos pasar una clave de API mediante el atributo data-api-key. Las solicitudes anónimas están limitadas a 10 conversiones por minuto. Las solicitudes autenticadas obtienen 30 por minuto.

Obtén tu clave de API gratuita en https://koalapic.com/dashboard/keys/

Ejemplos

Widget solo de compresión

<script src="https://koalapic.com/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-mode="compress"
        data-theme="light"
        data-accent-color="#10b981"></script>

Redimensionado con formatos limitados

<script src="https://koalapic.com/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-mode="resize"
        data-allowed-formats="jpg,png,webp"
        data-max-file-size="10"></script>

Varios widgets en una página

<div id="converter-1"></div>
<div id="converter-2"></div>
<script src="https://koalapic.com/static/widget/koalapic-widget.js"></script>
<script>
  KoalaPic.init('#converter-1', { mode: 'convert' });
  KoalaPic.init('#converter-2', { mode: 'compress' });
</script>

Vista previa en vivo

Así se ve el widget en acción: