API de personnalisation par IA

Les endpoints de personnalisation par IA génèrent deux variables d'e-mail par contact : une `ai_hook` (une accroche courte, axée sur la curiosité) et un `ai_subject` (une ligne d'objet). Les deux sont rédigés par un LLM à partir des données du site web du contact, dans la langue que vous demandez. Chaque génération nouvelle coûte €0,094 ; les accès au cache et les échecs ne sont jamais facturés. Les familles hook et subject partagent un contrat identique : remplacez `ai/hook` par `ai/subject` et le champ de réponse `hook` par `subject`.

Utilisez l'endpoint **synchrone** lorsque vous avez besoin d'une valeur immédiatement et pouvez attendre ~3 secondes : ```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"}' ``` Utilisez l'endpoint **batch** pour de nombreux contacts (jusqu'à 100). Il crée une tâche asynchrone, ne facture rien à la création et facture €0,094 par contact réussi — les contacts en échec sont gratuits. Le contact doit vous appartenir ; les contacts inconnus ou d'un autre client renvoient 404.

Une requête batch renvoie un `jobId` et une `pollUrl`. Sondez `GET /v1/jobs/{id}` jusqu'à ce que `status` soit `completed`, puis lisez les résultats par contact : ```bash # 1. Créer le 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. Sonder la pollUrl renvoyée curl https://api.meirra.com/v1/jobs/<jobId> \ -H "x-api-key: mk_live_your_key_here" ``` Les contacts réussis comportent un `hook` ; les contacts en échec n'en ont pas et n'ont pas été facturés.

Envoyez un en-tête `Idempotency-Key` sur toute requête modifiante (surtout `batch`) afin qu'une nouvelle tentative réseau ne crée jamais une tâche en double ni ne facture deux fois. Une relecture dans les 24 heures renvoie la réponse d'origine avec `X-Idempotent-Replayed: true` et n'est pas refacturée. Réutiliser une clé avec un corps différent renvoie `409 IDEMPOTENCY_KEY_CONFLICT` ; une clé de plus de 128 caractères renvoie `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>"}]}' ```

Exemples minimaux en Node et 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"]) ```

Lire des valeurs déjà générées ne coûte jamais de crédits. Récupérez la valeur la plus récente d'un contact avec `GET /v1/ai/hook/{leadId}`, ou listez vos générations avec `GET /v1/ai/hook?limit=50&status=complete&locale=en`. La liste est paginée (`limit` ≤ 100, `offset`) et filtrable par `locale`, `status` et `from` (ISO 8601). La valeur est `null` jusqu'à ce que son `status` soit `complete`.

Les générations IA ne sont jamais facturées en cas d'échec. Les codes que vous pouvez voir : • `LEAD_NOT_FOUND` (404) — le contact n'existe pas ou ne vous appartient pas • `NO_SCRAPE_DATA` (422) — aucune donnée de site web disponible pour générer • `GENERATION_QUALITY_FAILED` (422) — la sortie n'a pas respecté les règles de format après une nouvelle tentative • `UPSTREAM_TIMEOUT` / `UPSTREAM_UNAVAILABLE` (503) — le fournisseur d'IA est occupé ; réessayez sous peu • `INSUFFICIENT_BALANCE` (402) — solde insuffisant pour la requête (ou le batch entier) • `RATE_LIMIT_EXCEEDED` (429) — plus de 1000 requêtes/heure par clé

Appelez `GET /v1/ai/info` pour lire le catalogue en direct — variables, tarifs, langues prises en charge, modes de génération et limite de débit. Sans clé d'API, il renvoie le catalogue public ; avec une clé valide, il renvoie aussi votre solde et vos dépenses IA du mois en cours. C'est gratuit et jamais facturé.