API voor AI-personalisatie

De AI-personalisatie-endpoints genereren twee e-mailvariabelen per lead: een `ai_hook` (een korte, nieuwsgierig makende opening) en een `ai_subject` (een onderwerpregel). Beide worden door een LLM geschreven op basis van de websitegegevens van de lead, in de taal die je opvraagt. Elke nieuwe generatie kost €0,094; cachetreffers en mislukkingen worden nooit in rekening gebracht. De hook- en subject-families delen een identiek contract — vervang `ai/hook` door `ai/subject` en het responsveld `hook` door `subject`.

Gebruik het **synchrone** endpoint wanneer je meteen een waarde nodig hebt en ~3 seconden kunt wachten: ```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"}' ``` Gebruik het **batch**-endpoint voor veel leads (tot 100). Het maakt een asynchrone taak aan, brengt bij het aanmaken niets in rekening en rekent €0,094 per geslaagde lead — mislukte leads zijn gratis. De lead moet van jou zijn; onbekende of andermans leads geven 404 terug.

Een batchverzoek geeft een `jobId` en een `pollUrl` terug. Poll `GET /v1/jobs/{id}` totdat `status` `completed` is en lees dan de resultaten per lead: ```bash # 1. Maak de batch aan 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. Poll de teruggegeven pollUrl curl https://api.meirra.com/v1/jobs/<jobId> \ -H "x-api-key: mk_live_your_key_here" ``` Geslaagde leads bevatten een `hook`; mislukte leads niet en werden niet in rekening gebracht.

Stuur een `Idempotency-Key`-header bij elk wijzigend verzoek (vooral `batch`) zodat een netwerk-retry nooit een dubbele taak aanmaakt of dubbel in rekening brengt. Een herhaling binnen 24 uur geeft de oorspronkelijke respons terug met `X-Idempotent-Replayed: true` en wordt niet opnieuw belast. Dezelfde sleutel met een andere body geeft `409 IDEMPOTENCY_KEY_CONFLICT`; een sleutel langer dan 128 tekens geeft `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>"}]}' ```

Minimale voorbeelden in Node en 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"]) ```

Het lezen van al gegenereerde waarden kost nooit credits. Haal de meest recente waarde voor één lead op met `GET /v1/ai/hook/{leadId}`, of toon je generaties met `GET /v1/ai/hook?limit=50&status=complete&locale=en`. De lijst is gepagineerd (`limit` ≤ 100, `offset`) en filterbaar op `locale`, `status` en `from` (ISO 8601). De waarde is `null` totdat de `status` `complete` is.

AI-generaties worden bij mislukking nooit in rekening gebracht. De codes die je kunt zien: • `LEAD_NOT_FOUND` (404) — de lead bestaat niet of is niet van jou • `NO_SCRAPE_DATA` (422) — geen websitegegevens beschikbaar om te genereren • `GENERATION_QUALITY_FAILED` (422) — de uitvoer voldeed na een retry niet aan de opmaakregels • `UPSTREAM_TIMEOUT` / `UPSTREAM_UNAVAILABLE` (503) — de AI-provider is bezet; probeer het zo opnieuw • `INSUFFICIENT_BALANCE` (402) — onvoldoende saldo voor het verzoek (of de hele batch) • `RATE_LIMIT_EXCEEDED` (429) — meer dan 1000 verzoeken/uur per sleutel

Roep `GET /v1/ai/info` aan om de live catalogus te lezen — variabelen, prijzen, ondersteunde talen, generatiemodi en de snelheidslimiet. Zonder API-sleutel geeft het de openbare catalogus terug; met een geldige sleutel ook je saldo en je AI-uitgaven van de lopende maand. Het is gratis en wordt nooit in rekening gebracht.