API de personalización con IA

Los endpoints de personalización con IA generan dos variables de correo por contacto: un `ai_hook` (un gancho breve y basado en la curiosidad) y un `ai_subject` (una línea de asunto). Ambos los escribe un LLM a partir de los datos del sitio web del contacto, en el idioma que solicites. Cada generación nueva cuesta €0,094; los aciertos de caché y los fallos nunca se cobran. Las familias hook y subject comparten un contrato idéntico: cambia `ai/hook` por `ai/subject` y el campo de respuesta `hook` por `subject`.

Usa el endpoint **síncrono** cuando necesites un valor de inmediato y puedas esperar ~3 segundos: ```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 el endpoint **batch** para muchos contactos (hasta 100). Crea un trabajo asíncrono, no cobra nada al crearse y factura €0,094 por contacto correcto: los contactos fallidos son gratis. El contacto debe ser tuyo; los desconocidos o de otro cliente devuelven 404.

Una solicitud batch devuelve un `jobId` y una `pollUrl`. Sondea `GET /v1/jobs/{id}` hasta que `status` sea `completed` y luego lee los resultados por contacto: ```bash # 1. Crea el 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. Sondea la pollUrl devuelta curl https://api.meirra.com/v1/jobs/<jobId> \ -H "x-api-key: mk_live_your_key_here" ``` Los contactos correctos incluyen un `hook`; los fallidos no, y no se cobraron.

Envía una cabecera `Idempotency-Key` en cualquier solicitud que modifique datos (sobre todo `batch`) para que un reintento de red nunca cree un trabajo duplicado ni cobre dos veces. Una repetición dentro de 24 horas devuelve la respuesta original con `X-Idempotent-Replayed: true` y no se vuelve a cobrar. Reutilizar una clave con un cuerpo distinto devuelve `409 IDEMPOTENCY_KEY_CONFLICT`; una clave de más de 128 caracteres devuelve `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>"}]}' ```

Ejemplos mínimos en Node y 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"]) ```

Leer valores ya generados nunca cuesta créditos. Recupera el valor más reciente de un contacto con `GET /v1/ai/hook/{leadId}`, o lista tus generaciones con `GET /v1/ai/hook?limit=50&status=complete&locale=en`. La lista está paginada (`limit` ≤ 100, `offset`) y se puede filtrar por `locale`, `status` y `from` (ISO 8601). El valor es `null` hasta que su `status` sea `complete`.

Las generaciones de IA nunca se cobran si fallan. Los códigos que puedes ver: • `LEAD_NOT_FOUND` (404): el contacto no existe o no es tuyo • `NO_SCRAPE_DATA` (422): no había datos del sitio web para generar • `GENERATION_QUALITY_FAILED` (422): la salida no cumplió las reglas de formato tras un reintento • `UPSTREAM_TIMEOUT` / `UPSTREAM_UNAVAILABLE` (503): el proveedor de IA está ocupado; reintenta en breve • `INSUFFICIENT_BALANCE` (402): saldo insuficiente para la solicitud (o el batch completo) • `RATE_LIMIT_EXCEEDED` (429): más de 1000 solicitudes/hora por clave

Llama a `GET /v1/ai/info` para leer el catálogo en vivo: variables, precios, idiomas admitidos, modos de generación y límite de tasa. Sin clave de API devuelve el catálogo público; con una clave válida devuelve además tu saldo y tu gasto en IA del mes en curso. Es gratis y nunca se cobra.