API de plantillas | YouThumbAI Documentation

La API de plantillas da acceso a la biblioteca de plantillas de referencia de estilo de YouThumbAI. Las plantillas son imágenes seleccionadas que sirven de referencia visual a la IA al generar miniaturas.

Concepto

Una plantilla en YouThumbAI:

Es una imagen de referencia de estilo ya preparada
Está clasificada por tipo de contenido (gaming, tecnología, estilo de vida, etc.)
Puede ser destacada (recomendada) o normal
Sirve para guiar el estilo visual de la IA durante la generación

Cuando usas una plantilla, la IA:

Analiza la composición y la disposición
Extrae las combinaciones de colores y el estilo visual
Aplica una estética similar a tu miniatura generada
Coloca tu rostro manteniendo el estilo

Listar plantillas

Recupera las plantillas disponibles con filtrado opcional.

GET /api/templates

Parámetros de consulta

Parámetro	Tipo	Por defecto	Descripción
`category`	string	-	Filtrar por categoría
`isFeatured`	boolean	-	Filtrar solo las plantillas destacadas
`page`	number	1	Número de página
`limit`	number	20	Resultados por página (máx. 100)

Todas las plantillas:

bash

curl "https://youthumb.ai/api/templates" \
  -H "x-api-key: your_api_key"

Plantillas de gaming destacadas:

bash

curl "https://youthumb.ai/api/templates?category=gaming&isFeatured=true" \
  -H "x-api-key: your_api_key"

Paginado:

bash

curl "https://youthumb.ai/api/templates?page=2&limit=10" \
  -H "x-api-key: your_api_key"

Respuesta de la lista de plantillas

json

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "template-uuid-1",
        "name": "MrBeast Style Reaction",
        "description": "High energy reaction with bold colors",
        "category": "reaction",
        "imageUrl": "https://...",
        "thumbnailUrl": "https://...",
        "isFeatured": true,
        "tags": ["reaction", "viral", "colorful"],
        "createdAt": "2024-01-01T00:00:00.000Z"
      },
      {
        "id": "template-uuid-2",
        "name": "Tech Review Clean",
        "description": "Professional product showcase",
        "category": "tech",
        "imageUrl": "https://...",
        "thumbnailUrl": "https://...",
        "isFeatured": true,
        "tags": ["tech", "product", "clean"],
        "createdAt": "2024-01-02T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
}

Obtener los detalles de una plantilla

Recupera todos los detalles de una plantilla concreta.

GET /api/templates/{id}

Parámetro	Tipo	Descripción
`id`	string (UUID)	ID de la plantilla

bash

curl "https://youthumb.ai/api/templates/template-uuid-1" \
  -H "x-api-key: your_api_key"

Respuesta con los detalles de la plantilla

json

{
  "success": true,
  "data": {
    "id": "template-uuid-1",
    "name": "MrBeast Style Reaction",
    "description": "High energy reaction thumbnail perfect for viral content. Features bold colors, expressive face placement, and attention-grabbing composition.",
    "category": "reaction",
    "imageUrl": "https://...",
    "thumbnailUrl": "https://...",
    "isFeatured": true,
    "tags": ["reaction", "viral", "colorful", "mrbeast"],
    "metadata": {
      "style": "energetic",
      "colorPalette": ["#FF0000", "#FFFF00", "#00FF00"],
      "facePosition": "center-right"
    },
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-10T00:00:00.000Z"
  }
}

Error: plantilla no encontrada

json

{
  "success": false,
  "error": "Template not found"
}

Código de estado: 404 Not Found

Usar plantillas al generar miniaturas

Al crear una miniatura, referencia una plantilla con su ID:

json

{
  "prompt": "Shocked reaction to unbelievable news",
  "templateId": "template-uuid-1",
  "personId": "your-person-id"
}

La IA usará el estilo de la plantilla e incorporará:

Tu rostro (del perfil de persona)
Las modificaciones concretas de tu prompt
Las opciones avanzadas que indiques

Plantilla frente a URL de referencia de estilo

Método	Caso de uso
`templateId`	Usar una plantilla seleccionada de YouThumbAI
`styleReferenceUrl`	Usar cualquier URL de imagen externa como referencia
`youtubeUrl`	Extraer la miniatura de un video de YouTube como referencia

Puedes usar una de estas opciones por solicitud.

Categorías habituales

Categoría	Descripción
`reaction`	Videos de reacción y comentario
`gaming`	Gaming, esports, streams
`tech`	Análisis y tutoriales de tecnología
`vlog`	Vlogs y contenido de estilo de vida
`tutorial`	Contenido educativo y tutoriales prácticos
`challenge`	Retos y experimentos
`cinematic`	Miniaturas dramáticas estilo película

Ejemplo completo: JavaScript

javascript

const API = 'https://youthumb.ai/api';
const headers = { 'x-api-key': process.env.YOUTHUMB_API_KEY };

// Listar las plantillas destacadas
async function getFeaturedTemplates(category = null) {
  const params = new URLSearchParams({ isFeatured: 'true' });
  if (category) params.append('category', category);

  const response = await fetch(`${API}/templates?${params}`, { headers });
  return response.json();
}

// Obtener los detalles de una plantilla
async function getTemplate(templateId) {
  const response = await fetch(`${API}/templates/${templateId}`, { headers });
  return response.json();
}

// Generar una miniatura con una plantilla
async function generateWithTemplate(templateId, prompt, personId) {
  const response = await fetch(`${API}/thumbnails`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ templateId, prompt, personId }),
  });
  return response.json();
}

// Uso
const templates = await getFeaturedTemplates('gaming');
console.log('Gaming templates:', templates.data.templates.length);

const firstTemplate = templates.data.templates[0];
const thumbnail = await generateWithTemplate(
  firstTemplate.id,
  'Victory celebration after winning the tournament',
  'my-person-id'
);