Documentación técnica

⚡ Inicio rápido

Una sola llamada POST a /generate-multi recibe una imagen base + texto dinámico y devuelve la URL de la imagen renderizada lista para enviar por WhatsApp.

Copiar# Ejemplo mínimo — cURL
curl -X POST https://www.textonflow.com/generate-multi \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "mi-plantilla.jpg",
    "texts": [
      {
        "text": "Hola, {nombre}",
        "x": 100, "y": 80,
        "font_size": 72,
        "font_color": "#FFFFFF",
        "font_name": "DejaVuSans-Bold"
      }
    ],
    "vars": { "nombre": "Ana García" }
  }'

🌐 Base URL

Todos los endpoints son HTTPS. No se requiere API key para /generate-multi. El servidor está alojado en Railway (región US-West) con dominio personalizado via SiteGround.

🖼️ Renderizar imagen

Recibe una imagen base (plantilla) y un array de campos de texto, y devuelve una imagen PNG compuesta con todos los elementos renderizados.

Body (JSON)

Respuesta exitosa (200)

{
  "url": "https://www.textonflow.com/image/a3f8c2d1.png",
  "width": 1080,
  "height": 1080,
  "texts_rendered": 2
}

Devuelve el archivo PNG generado por /generate-multi. La URL completa viene en el campo url de la respuesta de renderizado — úsala directamente en el nodo de imagen de ManyChat.

✨ Generación de imágenes con IA

Genera imágenes con Google Gemini 2.5 Flash Image. El proceso es asíncrono: primero inicias el job y luego haces polling hasta recibir el resultado. El texto del prompt pasa por el modelo Gemini 2.0 Flash para enriquecimiento antes de generarse.

Body (JSON)

Estilos visuales disponibles

Respuesta (200)

{ "job_id": "550e8400-e29b-41d4-a716-446655440000" }

Estados de respuesta (polling)

// Pendiente — seguir haciendo polling cada 2 segundos
{ "status": "pending" }

// Completado — imagen disponible
{
  "status": "done",
  "url": "https://www.textonflow.com/storage/gen_abc123.png"
}

// Error — el modelo rechazó el prompt o falló la generación
{ "status": "error", "error": "Prompt rejected by safety filters" }

📱 Código QR

Genera un QR como PNG en base64, listo para usarse como overlay en una imagen de plantilla.

Body (JSON)

Respuesta (200)

{ "image": "data:image/png;base64,iVBORw0KGgo..." }

📦 Modelo — MultiTextRequest

El body completo del endpoint /generate-multi. Combina todos los elementos visuales en una sola solicitud atómica.

Copiar{
  "template_name": "plantilla-oferta.jpg",   // nombre en /templates/ o URL HTTPS
  "texts": [ /* array de TextField */ ],
  "vars": {                                     // variables de sustitución
    "nombre": "Ana García",
    "descuento": "30%"
  },
  "overlays": [ /* array de ImageOverlay */ ],
  "shapes": [ /* array de CanvasShape */ ],
  "filter_name": "none",
  "render_scale": 1,
  "watermark": false
}

✏️ Modelo — TextField

Define un bloque de texto con posición, tipografía, sombra, borde, fondo y efectos warp. Todos los campos son opcionales excepto text, x e y.

Posición y texto

Text wrap automático

Sombra del texto

Contorno (stroke) del texto

Caja de fondo del texto

🖼️ Modelo — ImageOverlay

Superpone una imagen sobre la plantilla. Ideal para fotos de perfil del cliente, logos o imágenes generadas por IA.

Ejemplo — foto de perfil circular

Copiar{
  "src": "https://cdn.example.com/foto-cliente.jpg",
  "x": 60, "y": 60,
  "width": 200, "height": 200,
  "mask_type": "circle",
  "mask_border_width": 4,
  "mask_border_color": "#FFFFFF",
  "mask_shadow_enabled": true,
  "mask_shadow_blur": 12
}

🔷 Modelo — CanvasShape

Forma geométrica renderizada debajo de los textos. Útil para crear fondos, marcos y divisores.

🔧 Variables dinámicas

Usa {nombre_variable} dentro de cualquier campo text de un TextField. El motor sustituye automáticamente cada llave con el valor correspondiente del objeto vars antes de renderizar.

Copiar{
  "texts": [
    { "text": "Hola, {nombre} 👋", "x": 100, "y": 80, "font_size": 64 },
    { "text": "Tu descuento: {descuento}", "x": 100, "y": 180, "font_size": 48 }
  ],
  "vars": {
    "nombre": "{{first name}}",    // custom field de ManyChat
    "descuento": "{{descuento_pct}}"
  }
}

⏱️ Contadores regresivos

Un TextField puede convertirse en un contador regresivo activando countdown_mode. El texto del campo se ignora y se reemplaza automáticamente por el tiempo restante.

Modo evento (fecha fija)

Copiar{
  "text": "",
  "x": 540, "y": 400,
  "font_size": 80,
  "font_color": "#FFFFFF",
  "countdown_mode": "event",
  "countdown_event_end_utc": "2026-12-31T23:59:59Z",
  "countdown_format": "DD:HH:MM:SS",
  "countdown_expired_text": "¡Oferta expirada!"
}

Modo urgencia (timer por suscriptor)

Copiar{
  "text": "",
  "x": 540, "y": 400,
  "countdown_mode": "urgency",
  "countdown_ts_var": "timer_final",  // nombre del custom field ManyChat
  "countdown_format": "HH:MM:SS",
  "countdown_urgency_hours": 3.0,        // cambia color al llegar a 3h
  "countdown_urgency_color": "#FF3B30"
}

🎨 Filtros de imagen

El campo filter_name de MultiTextRequest aplica un filtro de color a la imagen base antes de renderizar los textos.

Instagram

Cinematográficos / LUT

🌀 Efectos Warp (deformación de texto)

El campo warp_style de un TextField deforma el texto con distintas curvaturas. Combínalo con warp_bend (−100 a 100) para controlar la intensidad.

🔤 Fuentes disponibles

Pasa el nombre exacto en el campo font_name del TextField. Todas las fuentes están precargadas en el servidor.

🤖 Flujo ManyChat completo

Ejemplo de integración end-to-end: cuando un suscriptor activa el flujo, se genera una imagen personalizada y se envía por WhatsApp.

Copiar{
  "template_name": "mi-plantilla.jpg",
  "texts": [
    {
      "text": "Hola, {nombre} 🎉",
      "x": 540, "y": 120,
      "font_size": 72,
      "font_color": "#FFFFFF",
      "alignment": "center",
      "shadow_enabled": true,
      "shadow_blur": 6
    }
  ],
  "vars": {
    "nombre": "{{first name}}"
  }
}

⚠️ Códigos de error

📏 Límites y buenas prácticas

Límites técnicos

• Tamaño máximo recomendado de imagen base: 3840 × 3840 px (para render_scale 1)
• Imágenes externas (overlays, template_name por URL): máximo 15 segundos de timeout de descarga
• Tiempo de respuesta típico: 200–800 ms para plantillas locales con render_scale 1
• La generación IA puede tardar 8–30 segundos — usa el sistema de polling

Buenas prácticas

• Usa render_scale: 1 para flujos automáticos de ManyChat — es significativamente más rápido y el resultado es idéntico para pantallas móviles
• Subir plantillas al editor en lugar de URLs externas — elimina el delay de descarga y es más estable
• Tamaño recomendado de plantillas: 1080×1080 px para stories cuadradas, 1080×1920 px para vertical
• Fonts: Usa Montserrat-Bold o BebasNeue-Regular para texto de marketing — mayor impacto visual
• Overlays de fotos de perfil: Usa mask_type: "circle" con mask_border_width: 4 para un acabado profesional
• Variables: Si un custom field puede estar vacío en ManyChat, define un fallback en el texto: {nombre|Cliente} — TextOnFlow usa el valor antes del | si está disponible