API für KI-Personalisierung

Die Endpunkte zur KI-Personalisierung erzeugen zwei E-Mail-Variablen pro Lead: einen `ai_hook` (eine kurze, neugierig machende Eröffnung) und einen `ai_subject` (eine Betreffzeile). Beide werden von einem LLM aus den Website-Daten des Leads in der von dir angeforderten Sprache geschrieben. Jede neue Generierung kostet €0,094; Cache-Treffer und Fehlschläge werden nie berechnet. Die Hook- und Subject-Familien teilen sich einen identischen Vertrag — ersetze `ai/hook` durch `ai/subject` und das Antwortfeld `hook` durch `subject`.

Nutze den **synchronen** Endpunkt, wenn du sofort einen Wert brauchst und ~3 Sekunden warten kannst: ```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"}' ``` Nutze den **Batch**-Endpunkt für viele Leads (bis zu 100). Er erstellt einen asynchronen Auftrag, berechnet bei der Erstellung nichts und stellt €0,094 pro erfolgreichem Lead in Rechnung — fehlgeschlagene Leads sind kostenlos. Der Lead muss dir gehören; unbekannte oder fremde Leads geben 404 zurück.

Eine Batch-Anfrage gibt eine `jobId` und eine `pollUrl` zurück. Frage `GET /v1/jobs/{id}` ab, bis `status` `completed` ist, und lies dann die Ergebnisse pro Lead: ```bash # 1. Batch erstellen 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. Zurückgegebene pollUrl abfragen curl https://api.meirra.com/v1/jobs/<jobId> \ -H "x-api-key: mk_live_your_key_here" ``` Erfolgreiche Leads enthalten einen `hook`; fehlgeschlagene nicht und wurden nicht berechnet.

Sende einen `Idempotency-Key`-Header bei jeder verändernden Anfrage (besonders `batch`), damit ein Netzwerk-Retry nie einen Auftrag doppelt erstellt oder doppelt berechnet. Eine Wiederholung innerhalb von 24 Stunden gibt die ursprüngliche Antwort mit `X-Idempotent-Replayed: true` zurück und wird nicht erneut berechnet. Dieselbe Schlüssel mit anderem Body gibt `409 IDEMPOTENCY_KEY_CONFLICT` zurück; ein Schlüssel über 128 Zeichen gibt `400 INVALID_IDEMPOTENCY_KEY` zurück. ```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 Beispiele in Node und 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"]) ```

Das Lesen bereits generierter Werte kostet nie Guthaben. Rufe den neuesten Wert für einen Lead mit `GET /v1/ai/hook/{leadId}` ab oder liste deine Generierungen mit `GET /v1/ai/hook?limit=50&status=complete&locale=en` auf. Die Liste ist paginiert (`limit` ≤ 100, `offset`) und nach `locale`, `status` und `from` (ISO 8601) filterbar. Der Wert ist `null`, bis sein `status` `complete` ist.

KI-Generierungen werden bei Fehlschlag nie berechnet. Die möglichen Codes: • `LEAD_NOT_FOUND` (404) — der Lead existiert nicht oder gehört dir nicht • `NO_SCRAPE_DATA` (422) — keine Website-Daten zum Generieren verfügbar • `GENERATION_QUALITY_FAILED` (422) — die Ausgabe verfehlte die Formatregeln nach einem Retry • `UPSTREAM_TIMEOUT` / `UPSTREAM_UNAVAILABLE` (503) — der KI-Anbieter ist ausgelastet; bald erneut versuchen • `INSUFFICIENT_BALANCE` (402) — zu wenig Guthaben für die Anfrage (oder den ganzen Batch) • `RATE_LIMIT_EXCEEDED` (429) — über 1000 Anfragen/Stunde pro Schlüssel

Rufe `GET /v1/ai/info` auf, um den Live-Katalog zu lesen — Variablen, Preise, unterstützte Sprachen, Generierungsmodi und das Ratenlimit. Ohne API-Schlüssel gibt er den öffentlichen Katalog zurück; mit einem gültigen Schlüssel zusätzlich dein Guthaben und deine KI-Ausgaben im laufenden Monat. Er ist kostenlos und wird nie berechnet.