API_USAGE.md

Sofia-Cloud: Sistema de Créditos y API

🎯 Resumen Rápido

Sofia-Cloud ahora tiene:

• ✅ Creación automática de influencers (análisis + generación + almacenamiento en 1 llamada)
• ✅ Límites permanentes por tier (NO se resetean mensualmente)
• ✅ Rate-limiting inteligente para proteger tu inversión
• ✅ Tracking de uso acumulativo

📊 Límites por Tier (PERMANENTES)

Los límites son parte de la suscripción pagada. NO se resetean cada mes. Se resetean solo si:

1. El cliente sube a un tier superior
2. O solicita manualmente un reset (si paga extra)

Recurso	Free	Basic	Premium	Pro
Influencers	2	10	50	500
Stories	3	15	60	999
Imágenes	5	30	150	999
Videos	1	5	20	999
Contenido Total	10	50	300	999

Ejemplo

• Cliente contrata Basic = 10 influencers de por vida con Basic
• Cuando haya usado los 10, recibe error "Necesitas subir a un tier superior"
• Si sube a Premium = ahora tiene 50 influencers totales (no 60, mantiene los 10 anteriores en el nuevo límite)

🔧 Cómo Usar

1️⃣ Crear Influencer (Automático)

curl -X POST http://localhost:7860/api/influencers \
  -H "Content-Type: application/json" \
  -d '{
    "targetNiche": "Fashion",
    "includePets": true,
    "userId": "user123",
    "tier": "premium"
  }'

Respuesta exitosa:

{
  "success": true,
  "influencer": {
    "id": "cid123",
    "name": "Luna Style",
    "handle": "@lunastyle",
    "platform": "Instagram",
    "niche": "Fashion",
    "followers": 250000,
    "engagement": 3.5,
    "petCompanion": true,
    "petType": "dog"
  },
  "creditsRemaining": 49
}

Si no hay créditos:

{
  "success": false,
  "error": "Límite mensual de influencers_per_month alcanzado (50). Intenta el próximo mes.",
  "remaining": 0
}

---

2️⃣ Crear Story (Con Validación)

curl -X POST http://localhost:7860/api/storytelling \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Una influencer de moda que viaja por el mundo",
    "genre": "lifestyle",
    "totalEpisodes": 10,
    "userId": "user123",
    "tier": "premium"
  }'

Respuesta:

{
  "success": true,
  "story": {
    "id": "story123",
    "title": "Luna Viajera",
    "description": "Una influencer de moda...",
    "genre": "lifestyle",
    "totalEpisodes": 10,
    "status": "draft",
    "episodes": [
      {
        "id": "ep1",
        "episodeNum": 1,
        "title": "Capítulo 1: El Comienzo",
        "content": "..."
      }
    ]
  },
  "creditsRemaining": 59
}

---

3️⃣ Generar Imagen (Con Límite)

curl -X POST http://localhost:7860/api/generate/image \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Una modelo de moda en París",
    "platform": "instagram",
    "style": "realistic",
    "userId": "user123",
    "tier": "basic"
  }'

---

🚨 Manejo de Errores

Créditos agotados (429)

{
  "success": false,
  "error": "Límite mensual de influencers_per_month alcanzado (10). Intenta el próximo mes.",
  "remaining": 0
}

Falta prompty (400)

{
  "success": false,
  "error": "Prompt requerido"
}

Error de API (500)

{
  "success": false,
  "error": "Error al conectar con ZAI"
}

---

💡 Mejores Prácticas

1. Siempre incluir userId y tier

// ❌ Malo
POST /api/influencers
{ "targetNiche": "Fashion" }

// ✅ Bueno
POST /api/influencers
{ 
  "targetNiche": "Fashion",
  "userId": "user123",
  "tier": "premium"
}

2. Revisar creditsRemaining antes de siguiente acción

if (response.creditsRemaining === 0) {
  showUpgradePrompt(); // Sugerir upgrade
}

3. Manejar erro 429 (sin créditos)

if (error.status === 429) {
  showMessage("Límite mensual alcanzado. Intenta mañana o upgrade tu plan.");
}

---

📝 Notas Técnicas

• Los límites son PERMANENTES por el tier contratado (no se resetean mensualmente).
• El conteo incluye TODOS los recursos creados; para resetearse debe realizarse un cambio de tier o un reset manual pago.
• Si hay error en las APIs, se permite la acción (fallsafe seguro) para no bloquear al usuario por fallos externos.
• Los créditos se verifican ANTES de hacer la llamada (no gastas en errores).

---

🧾 Suscripciones por influencer

Cada cliente debe suscribirse individualmente a cada influencer con la que quiera interactuar en chat privado o contenido de pago. Las suscripciones son por influencer y por tier. Ejemplos:

• Usuario user123 se suscribe a la influencer Luna Style con el tier basic.
• Si quiere interactuar también con Ayla, debe suscribirse por separado a Ayla.

Endpoints

• Suscribirse:

curl -X POST http://localhost:7860/api/influencers/subscription \
  -H "Content-Type: application/json" \
  -d '{"userId":"user123","influencerId":"<influencer-id>","tier":"basic","price":9.99}'

• Listar suscripciones (por usuario o por influencer):

curl "http://localhost:7860/api/influencers/subscription?userId=user123"
curl "http://localhost:7860/api/influencers/subscription?influencerId=<influencer-id>"

• Cancelar/Anular suscripción:

curl -X DELETE "http://localhost:7860/api/influencers/subscription?id=<subscription-id>"

---

🎨 Qué Genera Automáticamente

Influencer (POST /api/influencers)

• ✅ Nombre único
• ✅ Handle/Username
• ✅ Platform (Instagram/TikTok/YouTube)
• ✅ Follower count estimado
• ✅ Engagement rate
• ✅ Niche específico
• ✅ Estilo visual
• ✅ Tipos de contenido
• ✅ Schedule de posts
• ✅ Tipo de monetización
• ✅ ¿Mascota? + tipo

Story (POST /api/storytelling)

• ✅ Título atractivo
• ✅ Sinopsis completa
• ✅ 3-10 episodios con contenido
• ✅ Metadata de análisis

Imagen (POST /api/generate/image)

• ✅ Imagen 1024x1024 en base64
• ✅ Prompt optimizado
• ✅ Validación de censura por plataforma

---

⚡ Próximas Mejoras (Sin romper)

• Video generation con límites
• Dashboard de uso mensual
• Exportar influencers a CSV/JSON
• Integración con OnlyFans/Monetización
• Batch creation (crear 10 influencers de una vez)