API de generacion IA
Endpoints /ai/generate, /ai/generate-template e /ai/improve, hard block 402 y limite 20/min.
Referencia de los endpoints del asistente IA. Todos van bajo JwtAuthGuard + TenantGuard y las tres generaciones estan limitadas a 20 peticiones/min por usuario.
Contexto comun
Los tres endpoints de generacion aceptan estos campos opcionales de contexto, ademas de los suyos propios:
| Campo | Notas |
|---|---|
templateId / versionId | Ancla el resultado a una plantilla/version |
locale | Idioma objetivo (hasta 10 caracteres) |
templateDescription | Descripcion del proposito (hasta 500) |
currentSubject | Asunto actual como referencia (hasta 200) |
variables | Lista de variables de la plantilla |
POST /ai/generate
Genera texto libre. Responde 200.
| Campo | Requerido | Notas |
|---|---|---|
prompt | Si | Instruccion (hasta 4000 caracteres) |
task | No | subjects, plain_text o general |
systemPrompt | No | Sobrescribe el prompt de sistema |
model | No | Fuerza un modelo concreto |
Respuesta: { content, model, tokens: { prompt, completion } }.
POST /ai/generate-template
Crea una plantilla completa. Responde 200.
| Campo | Requerido | Notas |
|---|---|---|
prompt | Si | Que email quieres (hasta 4000) |
tone | No | Tono deseado (hasta 120) |
model | No | Fuerza un modelo concreto |
Respuesta: { subject, preheader, html, model, tokens }.
POST /ai/improve
Reescribe HTML existente. Responde 200.
| Campo | Requerido | Notas |
|---|---|---|
html | Si | HTML a mejorar (hasta 50000 caracteres) |
instruction | Si | Que cambiar (hasta 500) |
model | No | Fuerza un modelo concreto |
Respuesta: { content, model, tokens }.
POST /ai/improve
Authorization: Bearer <accessToken>
X-Tenant-Id: {tenantId}
Content-Type: application/json
{
"html": "<h1>Hola</h1><p>...</p>",
"instruction": "Hazlo mas breve y con un CTA claro"
}
Hard block de tokens (402)
Antes de llamar al proveedor, la API estima el coste (ceil((longitud del prompt) / 4)) y comprueba tu saldo de tokens IA. Si el saldo no cubre el estimado, responde 402 AI_TOKEN_QUOTA_EXCEEDED y no consume nada — no hay grace period, a diferencia de la cuota de emails.
Limite de peticiones
Los tres endpoints de generacion estan limitados a 20 peticiones por minuto y usuario (contabilizado por user:<id>). Al superarlo, la API responde 429. Este limite endurece el limite global para proteger un recurso caro.
Saldo e historial
| Metodo | Ruta | Descripcion |
|---|---|---|
GET | /ai/balance | Saldo actual de tokens ({ balance }) |
GET | /ai/usage | Historial de consumo paginado (?page=&limit=) |
GET /ai/balance y GET /ai/usage no estan sujetos al limite de 20/min (solo al global).