API di personalizzazione con IA

Gli endpoint di personalizzazione con IA generano due variabili email per lead: un `ai_hook` (un'apertura breve, basata sulla curiosità) e un `ai_subject` (una riga oggetto). Entrambi sono scritti da un LLM a partire dai dati del sito web del lead, nella lingua che richiedi. Ogni generazione nuova costa €0,094; i risultati dalla cache e i fallimenti non vengono mai addebitati. Le famiglie hook e subject condividono un contratto identico: sostituisci `ai/hook` con `ai/subject` e il campo di risposta `hook` con `subject`.

Usa l'endpoint **sincrono** quando ti serve subito un valore e puoi attendere ~3 secondi: ```bash curl -X POST https://api.meirra.com/v1/ai/hook \ -H "x-api-key: mk_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"leadId": "<lead-uuid>", "locale": "en", "mode": "native"}' ``` Usa l'endpoint **batch** per molti lead (fino a 100). Crea un job asincrono, non addebita nulla alla creazione e fattura €0,094 per ogni lead riuscito — i lead falliti sono gratuiti. Il lead deve essere tuo; lead sconosciuti o di un altro cliente restituiscono 404.

Una richiesta batch restituisce un `jobId` e una `pollUrl`. Interroga `GET /v1/jobs/{id}` finché `status` non è `completed`, poi leggi i risultati per ogni lead: ```bash # 1. Crea il batch curl -X POST https://api.meirra.com/v1/ai/hook/batch \ -H "x-api-key: mk_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"leads": [{"leadId": "<uuid-1>"}, {"leadId": "<uuid-2>", "locale": "de", "mode": "translate"}]}' # 2. Interroga la pollUrl restituita curl https://api.meirra.com/v1/jobs/<jobId> \ -H "x-api-key: mk_live_your_key_here" ``` I lead riusciti includono un `hook`; quelli falliti no e non sono stati addebitati.

Invia un header `Idempotency-Key` su qualsiasi richiesta che modifica dati (soprattutto `batch`) così che un retry di rete non crei mai un job duplicato né addebiti due volte. Una ripetizione entro 24 ore restituisce la risposta originale con `X-Idempotent-Replayed: true` e non viene riaddebitata. Riutilizzare una chiave con un corpo diverso restituisce `409 IDEMPOTENCY_KEY_CONFLICT`; una chiave più lunga di 128 caratteri restituisce `400 INVALID_IDEMPOTENCY_KEY`. ```bash curl -X POST https://api.meirra.com/v1/ai/hook/batch \ -H "x-api-key: mk_live_your_key_here" \ -H "Idempotency-Key: my-batch-2026-05-29-001" \ -H "Content-Type: application/json" \ -d '{"leads": [{"leadId": "<lead-uuid>"}]}' ```

Esempi minimi in Node e Python: **Node (fetch):** ```javascript const res = await fetch("https://api.meirra.com/v1/ai/hook", { method: "POST", headers: { "x-api-key": process.env.MEIRRA_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ leadId, locale: "en" }), }); const { data } = await res.json(); console.log(data.hook); ``` **Python (requests):** ```python import os, requests res = requests.post( "https://api.meirra.com/v1/ai/hook", headers={"x-api-key": os.environ["MEIRRA_API_KEY"]}, json={"leadId": lead_id, "locale": "en"}, ) print(res.json()["data"]["hook"]) ```

Leggere valori già generati non costa mai crediti. Recupera il valore più recente di un lead con `GET /v1/ai/hook/{leadId}`, oppure elenca le tue generazioni con `GET /v1/ai/hook?limit=50&status=complete&locale=en`. L'elenco è paginato (`limit` ≤ 100, `offset`) e filtrabile per `locale`, `status` e `from` (ISO 8601). Il valore è `null` finché il suo `status` non è `complete`.

Le generazioni IA non vengono mai addebitate in caso di fallimento. I codici che potresti vedere: • `LEAD_NOT_FOUND` (404) — il lead non esiste o non è tuo • `NO_SCRAPE_DATA` (422) — nessun dato del sito web disponibile per generare • `GENERATION_QUALITY_FAILED` (422) — l'output non ha rispettato le regole di formato dopo un retry • `UPSTREAM_TIMEOUT` / `UPSTREAM_UNAVAILABLE` (503) — il fornitore IA è occupato; riprova a breve • `INSUFFICIENT_BALANCE` (402) — saldo insufficiente per la richiesta (o l'intero batch) • `RATE_LIMIT_EXCEEDED` (429) — oltre 1000 richieste/ora per chiave

Chiama `GET /v1/ai/info` per leggere il catalogo in tempo reale — variabili, prezzi, lingue supportate, modalità di generazione e limite di frequenza. Senza chiave API restituisce il catalogo pubblico; con una chiave valida restituisce anche il tuo saldo e la spesa IA del mese in corso. È gratuito e non viene mai addebitato.