API di generazione IA
Gli endpoint /ai/generate, /ai/generate-template e /ai/improve, l'hard block 402 e il limite 20/min.
Riferimento degli endpoint dell'assistente IA. Tutti girano sotto JwtAuthGuard + TenantGuard e le tre generazioni sono limitate a 20 richieste/min per utente.
Contesto comune
I tre endpoint di generazione accettano questi campi di contesto opzionali, oltre ai propri:
| Campo | Note |
|---|---|
templateId / versionId | Ancora il risultato a un template/versione |
locale | Lingua target (fino a 10 caratteri) |
templateDescription | Descrizione dello scopo (fino a 500) |
currentSubject | Oggetto attuale come riferimento (fino a 200) |
variables | Elenco delle variabili del template |
POST /ai/generate
Genera testo libero. Risponde 200.
| Campo | Obbligatorio | Note |
|---|---|---|
prompt | Si | Istruzione (fino a 4000 caratteri) |
task | No | subjects, plain_text o general |
systemPrompt | No | Sovrascrive il system prompt |
model | No | Forza un modello specifico |
Risposta: { content, model, tokens: { prompt, completion } }.
POST /ai/generate-template
Crea un template completo. Risponde 200.
| Campo | Obbligatorio | Note |
|---|---|---|
prompt | Si | L'email che vuoi (fino a 4000) |
tone | No | Tono desiderato (fino a 120) |
model | No | Forza un modello specifico |
Risposta: { subject, preheader, html, model, tokens }.
POST /ai/improve
Riscrive HTML esistente. Risponde 200.
| Campo | Obbligatorio | Note |
|---|---|---|
html | Si | HTML da migliorare (fino a 50000 caratteri) |
instruction | Si | Cosa cambiare (fino a 500) |
model | No | Forza un modello specifico |
Risposta: { content, model, tokens }.
POST /ai/improve
Authorization: Bearer <accessToken>
X-Tenant-Id: {tenantId}
Content-Type: application/json
{
"html": "<h1>Ciao</h1><p>...</p>",
"instruction": "Rendilo piu breve con una CTA chiara"
}
Hard block dei token (402)
Prima di chiamare il provider, l'API stima il costo (ceil((lunghezza del prompt) / 4)) e verifica il tuo saldo di token IA. Se il saldo non copre la stima, risponde 402 AI_TOKEN_QUOTA_EXCEEDED e non consuma nulla — non c'e grace period, a differenza della quota email.
Limite di richieste
I tre endpoint di generazione sono limitati a 20 richieste al minuto per utente (conteggiate per user:<id>). Al superamento, l'API risponde 429. Questo limite irrigidisce quello globale per proteggere una risorsa costosa.
Saldo e cronologia
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /ai/balance | Saldo attuale dei token ({ balance }) |
GET | /ai/usage | Cronologia di consumo paginata (?page=&limit=) |
GET /ai/balance e GET /ai/usage non sono soggetti al limite di 20/min (solo a quello globale).