Presets y códigos de error

Esta página documenta los presets de estilo disponibles y los códigos de error habituales de la API.

API de presets

Los presets son configuraciones de estilo predefinidas que guían el resultado visual de la IA. Dan acceso rápido a estilos de miniatura probados sin necesitar una imagen de plantilla.

Listar presets

GET /api/presets
bash
curl https://youthumb.ai/api/presets \
  -H "x-api-key: your_api_key"

Respuesta de presets

json
{
  "success": true,
  "data": [
    {
      "key": "mrbeast-viral",
      "label": "MrBeast Viral",
      "emoji": "🔥",
      "description": "High energy, bright colors, expressive faces"
    },
    ...
  ]
}

Presets disponibles

Clave del presetEtiquetaDescripción
freeFreeSin restricciones de estilo, solo el prompt
mrbeast-viralMrBeast ViralMucha energía, colores vivos, rostros expresivos
reaction-shockedReaction ShockedReacciones dramáticas, texto llamativo, impactante
before-afterBefore/AfterComparación dividida, revelación de una transformación
challenge-experimentChallengeEscenas de acción, suspenso, anticipo del resultado
gaming-esportsGamingColores neón, acción dinámica, elementos de juego
tech-reviewTech ReviewTomas de producto limpias, estética moderna
vlog-travelVlog/TravelFondos paisajísticos, conexión personal
tutorial-educationalTutorialVisuales claros, indicadores de pasos, útil
cinematic-filmCinematicEstilo póster de película, iluminación dramática
dramatic-intenseDramaticAlto contraste, emociones intensas
mystery-darkMysteryTonos oscuros, intriga, suspenso
luxury-premiumLuxuryElegante, sensación premium, sofisticado
officeCozy OfficeEscritorio ordenado, luz cálida, composición lista para el texto
youtube-studioYouTube StudioEstudio de creador, aro de luz, profesional

Usar presets

Al crear una miniatura, indica un preset con el parámetro presetKey:
json
{
  "prompt": "Excited reaction to new iPhone announcement",
  "presetKey": "tech-review",
  "personId": "your-person-id"
}

Preset frente a plantilla

MétodoDescripciónIdeal para
presetKeyPautas de estilo interpretadas por la IAGeneración rápida con un ambiente concreto
templateIdReferencia visual exactaReproducir un estilo de miniatura concreto
Puedes combinar ambos:
json
{
  "prompt": "Review of the latest MacBook",
  "presetKey": "tech-review",
  "templateId": "template-uuid",
  "personId": "your-person-id"
}

Códigos de error

Todos los errores de la API siguen un formato coherente:
json
{
  "success": false,
  "error": "Error message",
  "details": { ... }
}

Códigos de estado HTTP

EstadoNombreDescripción
400Bad RequestCuerpo o parámetros de la solicitud no válidos
401UnauthorizedClave API ausente o no válida
402Payment RequiredCréditos insuficientes
403ForbiddenAcceso denegado al recurso
404Not FoundEl recurso no existe
429Too Many RequestsLímite de solicitudes superado
500Internal Server ErrorError del lado del servidor

400 Bad Request

Se devuelve cuando falla la validación de la solicitud.
json
{
  "success": false,
  "error": "Validation error",
  "details": {
    "prompt": ["String must contain at least 3 character(s)"],
    "personId": ["Invalid uuid"]
  }
}
Causas habituales:
  • Faltan campos obligatorios
  • Tipos de campo no válidos
  • Valores fuera de los rangos permitidos
  • Uso de personId y personName a la vez

401 Unauthorized

Se devuelve cuando falla la autenticación.
json
{
  "success": false,
  "error": "Unauthorized"
}
Causas habituales:
  • Falta el encabezado x-api-key
  • Clave API no válida o caducada
  • Encabezado Authorization mal formado

402 Payment Required

Se devuelve cuando no tienes suficientes créditos.
json
{
  "success": false,
  "error": "Insufficient credits"
}
Solución: compra más créditos o mejora tu suscripción.

403 Forbidden

Se devuelve cuando no tienes acceso a un recurso.
json
{
  "success": false,
  "error": "Project does not belong to your organization"
}
Causas habituales:
  • Acceso a recursos de otra organización
  • Permisos insuficientes

404 Not Found

Se devuelve cuando un recurso no existe.
json
{
  "success": false,
  "error": "Project not found"
}
json
{
  "success": false,
  "error": "Person not found"
}
json
{
  "success": false,
  "error": "Template not found"
}

429 Too Many Requests

Se devuelve cuando superas los límites de solicitudes.
json
{
  "success": false,
  "error": "Rate limit exceeded"
}
Solución: espera antes de reintentar. Implementa un backoff exponencial.
javascript
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

500 Internal Server Error

Se devuelve cuando algo falla de nuestro lado.
json
{
  "success": false,
  "error": "Internal server error"
}
Solución: vuelve a intentarlo más tarde. Si persiste, contacta al soporte.

Referencia de reglas de validación

API de miniaturas

CampoReglas
promptObligatorio, 3-2000 caracteres
personIdOpcional, UUID válido
personNameOpcional, máx. 100 caracteres
presetKeyOpcional, debe ser una clave de preset válida
templateIdOpcional, UUID válido
styleReferenceUrlOpcional, URL válida
youtubeUrlOpcional, URL de YouTube válida
contentImagesOpcional, máx. 6 elementos
titleOpcional, máx. 200 caracteres
projectNameOpcional, máx. 100 caracteres

Opciones avanzadas

CampoReglas
variations1, 2, 3 o 4
faceExpressionneutral, happy, surprised, excited, serious, confident, keep-original
textPositiontop, center, bottom, none, keep-original
negativePromptMáx. 500 caracteres
clothingStylecasual, professional, sporty, elegant, streetwear, keep-original
faceEnhancementsubtle, normal, enhanced, keep-original
backgroundBlur0-100

API de personas

CampoReglas
nameObligatorio, 1-100 caracteres
descriptionOpcional, máx. 500 caracteres
imageIdsOpcional, array de UUID

Añadir imágenes a una persona

CampoReglas
imageIdsObligatorio, 1-10 UUID válidos

¿Necesitas ayuda?

Si encuentras problemas que no se tratan aquí:
  1. Revisa la documentación de la API para un uso correcto
  2. Verifica que tu clave API sea válida y tenga los permisos adecuados
  3. Revisa los detalles de la respuesta de error para ver los problemas de cada campo
  4. Contacta al soporte si los problemas persisten
Incluye la respuesta de error completa cuando contactes al soporte para resolverlo más rápido.