API de personalização com IA

Os endpoints de personalização com IA geram duas variáveis de e-mail por lead: um `ai_hook` (uma abertura curta, baseada na curiosidade) e um `ai_subject` (uma linha de assunto). Ambos são escritos por um LLM a partir dos dados do site do lead, no idioma que você solicitar. Cada geração nova custa €0,094; acertos de cache e falhas nunca são cobrados. As famílias hook e subject compartilham um contrato idêntico: troque `ai/hook` por `ai/subject` e o campo de resposta `hook` por `subject`.

Use o endpoint **síncrono** quando precisar de um valor de imediato e puder 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"}' ``` Use o endpoint **batch** para muitos leads (até 100). Ele cria um job assíncrono, não cobra nada na criação e fatura €0,094 por lead bem-sucedido — leads com falha são gratuitos. O lead deve ser seu; leads desconhecidos ou de outro cliente retornam 404.

Uma requisição batch retorna um `jobId` e uma `pollUrl`. Sonde `GET /v1/jobs/{id}` até que `status` seja `completed` e então leia os resultados por lead: ```bash # 1. Crie o 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. Sonde a pollUrl retornada curl https://api.meirra.com/v1/jobs/<jobId> \ -H "x-api-key: mk_live_your_key_here" ``` Leads bem-sucedidos incluem um `hook`; os que falharam não, e não foram cobrados.

Envie um cabeçalho `Idempotency-Key` em qualquer requisição que altere dados (sobretudo `batch`) para que uma nova tentativa de rede nunca crie um job duplicado nem cobre duas vezes. Uma repetição dentro de 24 horas retorna a resposta original com `X-Idempotent-Replayed: true` e não é cobrada de novo. Reutilizar uma chave com um corpo diferente retorna `409 IDEMPOTENCY_KEY_CONFLICT`; uma chave com mais de 128 caracteres retorna `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>"}]}' ```

Exemplos mínimos em 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"]) ```

Ler valores já gerados nunca custa créditos. Recupere o valor mais recente de um lead com `GET /v1/ai/hook/{leadId}`, ou liste suas gerações com `GET /v1/ai/hook?limit=50&status=complete&locale=en`. A lista é paginada (`limit` ≤ 100, `offset`) e filtrável por `locale`, `status` e `from` (ISO 8601). O valor é `null` até que seu `status` seja `complete`.

As gerações de IA nunca são cobradas em caso de falha. Os códigos que você pode ver: • `LEAD_NOT_FOUND` (404) — o lead não existe ou não é seu • `NO_SCRAPE_DATA` (422) — nenhum dado do site disponível para gerar • `GENERATION_QUALITY_FAILED` (422) — a saída não cumpriu as regras de formato após uma nova tentativa • `UPSTREAM_TIMEOUT` / `UPSTREAM_UNAVAILABLE` (503) — o provedor de IA está ocupado; tente novamente em breve • `INSUFFICIENT_BALANCE` (402) — saldo insuficiente para a requisição (ou o batch inteiro) • `RATE_LIMIT_EXCEEDED` (429) — mais de 1000 requisições/hora por chave

Chame `GET /v1/ai/info` para ler o catálogo ao vivo — variáveis, preços, idiomas suportados, modos de geração e limite de taxa. Sem chave de API, retorna o catálogo público; com uma chave válida, retorna também seu saldo e seu gasto com IA no mês corrente. É gratuito e nunca é cobrado.