Documentação da API

Autenticação

Toda chamada leva a sua credencial no cabecalho:

Authorization: Bearer <api_id>.<segredo>

O api_id comeca com ab_. O segredo aparece uma unica vez, no momento em que a credencial e' criada — nem o operador consegue recupera-lo depois, porque o que fica guardado e' um hash scrypt. Perdeu, gere outra credencial.

Clientes da versao anterior podem continuar usando os cabecalhos X-Customer-Api-Id e X-Secret; as duas formas valem.

Chamadas longas

Chamadas de GPU podem levar de segundos a minutos. Duas formas de esperar:

• Sincrona (padrao): a resposta so volta quando o trabalho termina. Simples,

e o que quase todo mundo quer. Use timeout de cliente de pelo menos 180 s — timeout curto faz voce desistir de um trabalho que a placa ja comecou.

• Assincrona: envie com "async": true, receba um job_id na hora e acompanhe

por GET /v1/jobs/{job_id} ou pelo fluxo de eventos em GET /v1/jobs/{job_id}/stream. E' o caminho certo para lote e para transcricao de audio longo.

Reenvio seguro

Um pedido de GPU pode levar minutos. Se o seu cliente estourar o proprio timeout e reenviar, sem cuidado voce paga duas vezes e ocupa a placa duas vezes.

Mande um cabecalho Idempotency-Key com um valor unico por pedido — um UUID serve:

Idempotency-Key: 4f9c2a1e-7b3d-4c8a-9e21-0a5f6d8b3c74

O que acontece no reenvio com a mesma chave:

• se o primeiro pedido ainda esta rodando, voce recebe 409 com o job_id

para acompanhar, em vez de disparar um segundo trabalho;

• se ele ja terminou, voce recebe a mesma resposta, com o cabecalho

Idempotency-Replayed: true. Nao consome cota e nao toca a placa.

A chave vale por 24 horas e considera o corpo do pedido: reusar a mesma chave com um conteudo diferente executa normalmente, em vez de devolver a resposta antiga — esse e' o erro mais comum de quem usa idempotencia pela primeira vez.

Resposta muito grande (imagem em base64, por exemplo) nao e' guardada para repeticao; nesse caso o reenvio devolve o job_id para voce buscar o resultado.

Cache determinístico

Chamada com temperature: 0 e' deterministica por contrato: a mesma entrada devolve a mesma saida. Guardamos essa resposta por 24 horas e servimos as repeticoes sem tocar a placa.

Medido na nossa carga real: 66% dos pedidos vem com temperatura 0, e 52,6% deles sao repeticoes exatas — cerca de um terco do trabalho era refeito. Uma resposta em cache volta em ~40 ms, contra segundos de geracao.

Como saber que veio do cache: a resposta traz do_cache: true. Sem isso, uma latencia de 40 ms onde voce espera 4 s pareceria defeito.

Com amostragem nao cacheamos. Se voce mandou temperature maior que zero, pediu variacao — servir a mesma resposta seria quebrar o que voce contratou para economizar placa nossa, e voce nao teria como saber. Se quiser cache mesmo assim, mande "cache": true; para desligar num pedido deterministico, "cache": false.

A chave considera modelo, quantizacao, mensagens, teto de tokens e cada parametro de amostragem. Mudou qualquer um, e' outro pedido.

Erros e limites

Erros vem sempre no mesmo formato, com um codigo estavel para o seu codigo tratar e uma mensagem para pessoas lerem:

{"erro": {"codigo": "cota_mensal_esgotada", "mensagem": "..."}}

HTTP	codigo	o que fazer
401	credencial_invalida	conferir api_id e segredo
403	rota_nao_permitida	a rota nao esta no seu plano; fale conosco
403	credencial_inativa	credencial desativada no painel
429	limite_por_minuto	esperar o Retry-After e tentar de novo
429	limite_simultaneas	reduzir chamadas em paralelo
429	cota_mensal_esgotada	subir de plano ou esperar o proximo mes
404	nao_encontrado	o job ou arquivo nao e' seu, ou nao existe
409	em_andamento	mesmo Idempotency-Key ainda em execucao
502	upstream_indisponivel	falha nossa; tente de novo com espera

Todo 429 traz Retry-After em segundos. Respeite-o: tentar em laco transforma o seu proprio limite numa tempestade que atrasa as suas outras chamadas.

Texto e conversa

Geracao de texto com modelo instruido, servida por Tesla T4 dedicadas. Compativel com o formato da OpenAI: se o seu codigo ja fala com a OpenAI, troque a URL base e a chave e pronto.

POST /api/v1/ai/v1/chat/completions escopo llm
Conversa no formato OpenAI
O caminho padrao para quase tudo: perguntas, resumo, extracao, classificacao, reescrita.
parâmetro	tipo	padrão	descrição
model	string	padrao do servidor	Nome do modelo. Apelido desconhecido cai no modelo padrao do servidor em vez de dar erro.
messages	array	obrigatório	Lista de mensagens com `role` (system/user/assistant) e `content`.
max_tokens	inteiro	1024	Teto de tokens gerados. Menor e' mais rapido e mais barato.
temperature	numero	0.7	0 e' deterministico; 0.7 e' criativo.
stream	booleano	false	Devolve os tokens conforme saem, em SSE.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/chat/completions \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "Voce responde em portugues, de forma direta."},
      {"role": "user", "content": "Resuma o que e' um laudo pericial em duas frases."}
    ],
    "max_tokens": 300,
    "temperature": 0.3
  }'
Resposta
{
  "id": "chatcmpl-8f2a...",
  "object": "chat.completion",
  "created": 1788694014,
  "model": "Qwen/Qwen2.5-7B-Instruct",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Um laudo pericial e' um documento..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 48, "completion_tokens": 62, "total_tokens": 110}
}
`max_tokens` e' o que mais mexe no seu tempo de resposta e na sua cota: dobrar o teto costuma dobrar o tempo.
Com `stream: true` os tokens chegam em `text/event-stream`.
POST /api/v1/ai/v1/completions escopo llm

Completacao simples (formato legado)

Compatibilidade com codigo antigo que usa `prompt` em vez de `messages`.

parâmetro	tipo	padrão	descrição
prompt	string	obrigatório	O texto a completar.
max_tokens	inteiro	1024	Teto de tokens gerados.

POST /api/v1/ai/v1/llm/generate pode ser assíncronaescopo llm

Geracao nativa, com controle de job

Quando voce quer o `job_id` para acompanhar progresso ou cancelar.

parâmetro	tipo	padrão	descrição
prompt	string	obrigatório	O texto de entrada.
async	booleano	false	Retorna na hora com o job_id.
priority	inteiro	do plano	0 e' a maior. Seu plano define o padrao.

POST /api/v1/ai/api/generate escopo llm
Geracao no formato Ollama
Para quem ja tem cliente Ollama: nao muda uma linha de codigo.
parâmetro	tipo	padrão	descrição
model	string	obrigatório	Nome no estilo Ollama, ex.: `llama3.2`.
prompt	string	obrigatório	O texto de entrada.
Nomes de modelo do Ollama sao traduzidos para o modelo equivalente daqui; nao ha download de modelo pelo cliente.
POST /api/v1/ai/api/chat escopo llm

Conversa no formato Ollama

Mesmo caso acima, para o endpoint de chat do Ollama.

parâmetro	tipo	padrão	descrição
model	string	obrigatório	Nome no estilo Ollama.
messages	array	obrigatório	Mensagens da conversa.

Análise de texto

Sentimento, classificação, resumo e extração de campos a partir de texto livre, com **saída estruturada e validada** — não texto solto que você precisa interpretar. Roda no modelo do próprio cluster: o seu texto não sai da nossa infraestrutura e não há custo por chamada de terceiro.

GET /api/v1/ai/v1/texto escopo llm

Tarefas de texto disponíveis

Descobrir o que dá para pedir e quais campos cada tarefa devolve.

POST /api/v1/ai/v1/texto/sentimento pode ser assíncronaescopo llm
Sentimento
Classificar avaliações, chamados ou comentários como positivo, neutro ou negativo, com o trecho que justifica.
parâmetro	tipo	padrão	descrição
textos	array	obrigatório	Lista de textos. Até 500 por chamada, 8.000 caracteres cada.
async	booleano	false	Acima de algumas dezenas, use assíncrono.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/texto/sentimento \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "textos": [
      "Chegou antes do prazo e e exatamente como na foto.",
      "Paguei frete expresso e demorou nove dias. Ninguem respondeu."
    ]
  }'
Resposta
{
  "tarefa": "sentimento",
  "modelo": "Qwen/Qwen2.5-7B-Instruct",
  "dados": {"textos": 2, "com_falha": 0},
  "resultados": [
    {"indice": 0, "ok": true, "sentimento": "positivo", "confianca": 0.9,
     "trecho": "Chegou antes do prazo"},
    {"indice": 1, "ok": true, "sentimento": "negativo", "confianca": 0.75,
     "trecho": "demorou nove dias"}
  ]
}
**A falha é por item, não por lote.** Um texto que o modelo não conseguir estruturar volta com `ok: false` e o motivo — os outros 499 que a placa já processou não se perdem.
Cada texto é uma geração, então um lote de 500 leva minutos. Use `async` e acompanhe pelo `job_id`.
POST /api/v1/ai/v1/texto/classificacao pode ser assíncronaescopo llm
Classificação por categoria
Colocar cada texto numa das categorias que você definir.
parâmetro	tipo	padrão	descrição
textos	array	obrigatório	Lista de textos.
categorias	array	obrigatório	As opções possíveis, por exemplo entrega, produto, atendimento.
Quando nenhuma categoria serve, o modelo responde `outra` em vez de forçar uma errada.
POST /api/v1/ai/v1/texto/resumo pode ser assíncronaescopo llm

Resumo

Resumir cada texto em uma ou duas frases, com o tema.

parâmetro	tipo	padrão	descrição
textos	array	obrigatório	Lista de textos.

POST /api/v1/ai/v1/texto/extracao pode ser assíncronaescopo llm

Extração de campos

Puxar campos estruturados de texto livre — valor, prazo, produto, o que você definir.

parâmetro	tipo	padrão	descrição
textos	array	obrigatório	Lista de textos.
campos	objeto	obrigatório	Nome e significado de cada campo. Exemplo: {"valor": "o valor em reais", "prazo": "o prazo citado"}

Embeddings e busca semantica

Vetores para busca por significado, deduplicacao e RAG, mais reordenacao de resultados. Servidos por uma placa separada da de texto — nao disputam fila com a geracao.

POST /api/v1/ai/v1/embeddings escopo embeddings
Vetores no formato OpenAI
Indexar documentos e transformar a pergunta do usuario em vetor.
parâmetro	tipo	padrão	descrição
input	string ou array	obrigatório	Um texto ou uma lista deles. Lista e' muito mais eficiente.
model	string	BAAI/bge-m3	Apelido desconhecido cai no padrao.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/embeddings \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{"input": ["primeiro documento", "segundo documento"]}'
Resposta
{
  "object": "list",
  "model": "BAAI/bge-m3",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [-0.0224, -0.0373, ...]},
    {"object": "embedding", "index": 1, "embedding": [0.0238, -0.0105, ...]}
  ],
  "usage": {"prompt_tokens": 12, "total_tokens": 12}
}
1.024 dimensoes. Mande em lote: cem textos numa chamada custam uma unidade de cota, cem chamadas custam cem.
POST /api/v1/ai/v1/rerank escopo embeddings

Reordenar por relevancia

Depois de recuperar 50 candidatos por vetor, escolher os 5 melhores. Melhora RAG mais que trocar de modelo de embedding.

parâmetro	tipo	padrão	descrição
query	string	obrigatório	A pergunta.
documents	array	obrigatório	Os candidatos a reordenar.
top_n	inteiro	todos	Quantos devolver.

Audio e transcricao

Transcricao com Whisper large-v3, com marcacao de tempo e deteccao de idioma.

POST /api/v1/ai/v1/audio/transcriptions pode ser assíncronaescopo asr
Transcrever (formato OpenAI)
Envio direto do arquivo, em multipart. O caminho mais simples.
parâmetro	tipo	padrão	descrição
file	arquivo	obrigatório	mp3, wav, m4a, ogg, flac, mp4.
language	string	auto	Codigo ISO. Vazio detecta sozinho.
response_format	string	verbose_json	`json`, `verbose_json`, `text`, `srt`, `vtt`.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/audio/transcriptions \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -F file=@reuniao.mp3 \
  -F response_format=srt
Audio longo e' o caso classico para `async`: uma hora de gravacao nao cabe num timeout de cliente confortavel.
`srt` e `vtt` saem prontos para legenda.
POST /api/v1/ai/v1/asr/transcribe pode ser assíncronaescopo asr

Transcrever por file_id ou URL

Quando o audio ja esta no nosso armazenamento ou acessivel por URL.

parâmetro	tipo	padrão	descrição
file_id	string	opcional	Devolvido por `POST /v1/files`.
url	string	opcional	Alternativa ao file_id.

Sintese de voz

Kokoro-82M na nossa GPU. 34x tempo real: 7,8 s de fala em 0,23 s. O texto nao sai da nossa infraestrutura — o que num produto de saude ou juridico costuma ser o requisito, nao o detalhe.

POST /api/v1/ai/v1/audio/speech escopo voz
Falar um texto (formato OpenAI)
Devolve os BYTES do audio, nao JSON — igual ao OpenAI, entao quem ja usa a biblioteca deles nao muda o codigo.
parâmetro	tipo	padrão	descrição
input	string	obrigatório	Texto a falar. Ate 20.000 caracteres.
voice	string	pf_dora	Veja `GET /v1/audio/voices`.
idioma	string	pt-br	`pt-br`, `en-us` ou `es`.
speed	number	1.0	Entre 0,5 e 2,0.
response_format	string	wav	`wav` ou `pcm`. Nao geramos mp3 nem opus.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/audio/speech \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{"input":"Sua consulta esta confirmada para quinta-feira.","voice":"pf_dora"}' \
  --output fala.wav
Texto longo e' quebrado na PONTUACAO, nao a cada N caracteres: cortar no meio de uma palavra produz emenda audivel, cortar na virgula cai onde o ouvido ja espera pausa.
Declaramos so' `wav` e `pcm`. Devolver WAV rotulado de mp3 quebraria no seu lado sem deixar pista de onde.
O cabecalho `X-Audio-Duration-S` traz a duracao do que veio.
GET /api/v1/ai/v1/audio/voices escopo voz

Vozes disponiveis

Quais vozes existem em cada idioma, e qual e' a padrao.

Geracao de imagem

SDXL-Turbo numa Tesla T4 dedicada a midia. Catalogo 1024x1024 em ~4 s.

POST /api/v1/ai/v1/images/generations escopo images
Gerar imagem a partir de texto
Foto de produto, banner, ilustracao.
parâmetro	tipo	padrão	descrição
prompt	string	obrigatório	A descricao do que gerar.
n	inteiro	1	Quantas imagens.
size	string	1024x1024	Ex.: `1024x1024`, `1216x640`.
response_format	string	url	`b64_json` devolve os bytes; `url` devolve um link.
seed	inteiro	opcional	Fixe para reproduzir a mesma imagem.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/images/generations \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "frasco de vitamina C em fundo branco, foto de catalogo",
    "n": 1, "size": "1024x1024", "response_format": "b64_json"
  }'
Resposta
{
  "created": 1788694014,
  "model": "stabilityai/sdxl-turbo",
  "seed": 1833471805,
  "job_id": "job_5b44d28084834da8",
  "data": [{"width": 1024, "height": 1024, "b64_json": "iVBORw0KGgoAAAANS..."}]
}
`b64_json` e' o caminho rapido: os bytes voltam na resposta e nada precisa ser buscado depois.
Medido: 1024x1024 em ~5,5 s ponta a ponta, ~1,6 MB de PNG.

Visao computacional

Descrever imagem, responder perguntas sobre ela e extrair texto.

POST /api/v1/ai/v1/vision/analyze escopo vision

Analisar uma imagem

Descricao, pergunta sobre a imagem, leitura de contexto visual.

parâmetro	tipo	padrão	descrição
file_id	string	opcional	Imagem ja enviada.
url	string	opcional	Alternativa ao file_id.
prompt	string	descreva a imagem	O que voce quer saber.

POST /api/v1/ai/v1/vision/ocr escopo vision

Extrair todo o texto de uma imagem

Documento fotografado, print de tela, placa, formulario.

parâmetro	tipo	padrão	descrição
file_id	string	opcional	Imagem ja enviada.
url	string	opcional	Alternativa ao file_id.

Arquivos

Envie uma vez, use em varias chamadas. Arquivos expiram sozinhos.

POST /api/v1/ai/v1/files escopo files

Enviar arquivo

Audio para transcrever, imagem para analisar.

parâmetro	tipo	padrão	descrição
file	arquivo	obrigatório	O conteudo, em multipart.

Exemplo

curl https://abintel.digital/api/v1/ai/v1/files \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -F file=@entrevista.wav

Resposta

{"id": "file_9c1e...", "bytes": 20971520, "mime": "audio/wav"}

GET /api/v1/ai/v1/files/{file_id} escopo files

Baixar arquivo

Buscar um resultado que ficou guardado.

GET /api/v1/ai/v1/files/{file_id}/meta escopo files

Dados do arquivo

Tamanho, tipo e validade, sem baixar o conteudo.

DELETE /api/v1/ai/v1/files/{file_id} escopo files

Apagar agora

Nao esperar a expiracao — util para dado sensivel.

Acompanhamento de trabalho

Para chamadas assincronas: acompanhar, aguardar e cancelar.

GET /api/v1/ai/v1/jobs/{job_id} escopo jobs

Consultar um trabalho

Saber se terminou e pegar o resultado.

GET /api/v1/ai/v1/jobs/{job_id}/wait escopo jobs

Aguardar ate terminar

Long-poll: uma chamada so, sem laco de consulta do seu lado.

GET /api/v1/ai/v1/jobs/{job_id}/stream escopo jobs

Acompanhar em tempo real

Eventos SSE com progresso e, na geracao de texto, os tokens.

GET /api/v1/ai/v1/jobs escopo jobs
Listar seus trabalhos recentes
Auditoria e depuracao do seu lado.
A lista traz apenas os seus trabalhos.
DELETE /api/v1/ai/v1/jobs/{job_id} escopo jobs

Cancelar

Trabalho na fila sai na hora; em execucao para no proximo ponto seguro.

Análise de negócio

Modelos de ML sobre a sua tabela de clientes: risco, segmentação e propensão. Você manda os registros, a plataforma treina, escolhe o melhor modelo por validação cruzada e devolve a pontuação com os fatores que pesaram. Roda em CPU, então não disputa fila com a geração de texto.

GET /api/v1/ai/v1/analitica escopo analitica

Análises disponíveis

Descobrir o que dá para pedir e quais colunas cada uma exige.

POST /api/v1/ai/v1/analitica/features escopo analitica
Extrato para tabela de cliente
Transformar o seu extrato de transações na tabela por cliente que as outras análises pedem. **Comece por aqui** se o que você tem é uma linha por compra.
parâmetro	tipo	padrão	descrição
data[].customer_id	string	obrigatório	Quem comprou. Aceita `cliente`, `id_cliente`.
data[].data	data	obrigatório	Quando. Aceita `date`, `data_compra`.
data[].valor	número	opcional	Quanto. Valor negativo é tratado como devolução.
parametros.marco	data	última transação da base	Referência para a recência.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/analitica/features \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"cliente": "c001", "data_compra": "2026-03-14", "receita": 320.00},
      {"cliente": "c001", "data_compra": "2026-05-02", "receita": 180.50},
      {"cliente": "c002", "data_compra": "2026-01-09", "receita": 640.00}
    ]
  }'
Resposta
{
  "dados": {"linhas_usadas": 3, "clientes": 2, "marco": "2026-05-02",
            "marco_origem": "ultima transacao da base"},
  "resumo": {"compra_unica": 1, "atrasados": 1, "com_devolucao": 0},
  "resultados": [
    {"customer_id": "c001", "recencia": 0, "frequencia": 2, "valor": 500.5,
     "ticket_medio": 250.25, "meses_ativo": 1.61,
     "intervalo_medio_dias": 49.0, "devolucoes": 0, "atrasado": false}
  ]
}
A saída entra **direto** em `/rfm`, `/churn`, `/valor_de_vida` e `/agrupamento`, sem retrabalho.
A recência é contada a partir da **última transação da base**, não de hoje: contar de hoje faria a mesma base dar resultados diferentes em dois dias.
Cliente de compra única fica com intervalo `null`, não zero — zero inflaria a regularidade de quem comprou uma vez e sumiu.
Valor negativo conta no total e **não** na frequência, senão quem comprou e devolveu viraria cliente frequente.
POST /api/v1/ai/v1/analitica/churn pode ser assíncronaescopo analitica
Risco de cancelamento
Estimar quem vai cancelar, com os fatores que mais pesam e uma ação sugerida por faixa de risco.
parâmetro	tipo	padrão	descrição
data	array	obrigatório	Um objeto por cliente. Aceita apelidos de coluna: `tenure_days`, `avg_sessions_per_week`, `nps_score`.
data[].churned	0 ou 1	obrigatório	1 = cancelou, 0 = ficou. Ao menos 10 registros rotulados; quem vier sem rótulo é pontuado.
async	booleano	false	Volume grande: receba o job_id na hora.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/analitica/churn \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"customer_id":"c1","tenure":36,"usage_frequency":4.2,
       "service_tickets":0,"nps":9,"payment_events":14,"churned":0},
      {"customer_id":"c2","tenure":5,"usage_frequency":0.8,
       "service_tickets":6,"nps":3,"payment_events":4,"churned":1},
      {"customer_id":"c3","tenure":11,"usage_frequency":1.5,
       "service_tickets":3,"nps":5,"payment_events":7}
    ]
  }'
Resposta
{
  "analise": "churn",
  "modelo": {
    "escolhido": "regressao_logistica",
    "metrica": "roc_auc por validacao cruzada",
    "comparacao": {
      "regressao_logistica": {"roc_auc_medio": 0.912, "desvio": 0.021, "dobras": 5},
      "floresta_aleatoria":  {"roc_auc_medio": 0.894, "desvio": 0.033, "dobras": 5}
    }
  },
  "dados": {"registros": 300, "rotulados": 267, "positivos": 75},
  "fatores": [{"variavel": "tenure", "peso": 0.0062}],
  "resultados": [
    {"customer_id": "c3", "probabilidade": 0.71, "faixa": "media",
     "recomendacao": "Risco medio: contato proativo e programa de fidelidade.",
     "usado_no_treino": false}
  ]
}
Registros sem a coluna de rótulo **também são pontuados** — são justamente os que você quer prever.
Valor ausente é imputado pela mediana, e a resposta diz quantos foram, para você não confundir estimativa com medição.
Teto de 100.000 registros por chamada.
POST /api/v1/ai/v1/analitica/risco_credito pode ser assíncronaescopo analitica

Risco de crédito

Estimar inadimplência e sugerir política de limite.

parâmetro	tipo	padrão	descrição
data[].inadimplente	0 ou 1	obrigatório	1 = inadimpliu, 0 = pagou.

POST /api/v1/ai/v1/analitica/propensao pode ser assíncronaescopo analitica

Propensão a converter

Compra, resposta a campanha ou upgrade — a coluna a prever é sua.

parâmetro	tipo	padrão	descrição
parametros.rotulo	string	converteu	Nome da coluna 0/1 a prever.

POST /api/v1/ai/v1/analitica/rfm escopo analitica
Segmentação RFM
Classificar por recência, frequência e valor, e nomear o segmento.
parâmetro	tipo	padrão	descrição
data[].recencia	número	obrigatório	Dias desde a última compra.
data[].frequencia	número	obrigatório	Compras no período.
data[].valor	número	obrigatório	Total gasto.
parametros.quintis	inteiro	5	Faixas por dimensão (3 a 10).
Recência é invertida: quem comprou há menos tempo recebe nota maior.
POST /api/v1/ai/v1/analitica/previsao pode ser assíncronaescopo analitica
Previsão de série temporal
Prever receita, custo, unidades ou qualquer série com data e valor, com intervalo de confiança.
parâmetro	tipo	padrão	descrição
data[].data	data	obrigatório	A data do período. Aceita `date`, `periodo`, `ds`.
data[].valor	número	obrigatório	O valor. Aceita `receita`, `custo`, `unidades`.
parametros.horizonte	inteiro	3	Quantos períodos prever (1 a 36).
parametros.origens	inteiro	4	Pontos de validação temporal.
Compara sempre contra baselines ingênuas (repetir o último valor, repetir o mesmo período do ciclo anterior, e reta). **Se nenhum modelo ganhar da baseline, a resposta diz isso** — é sinal de série curta, ruidosa ou sem padrão estável.
A escolha é por origem móvel: treina até um ponto, prevê o seguinte, anda e repete. Julgar pelo ajuste na própria série premiaria o modelo que decora o passado.
Mínimo de 8 períodos.
Transações na mesma data são somadas — mande agregado ou bruto, os dois funcionam.
POST /api/v1/ai/v1/analitica/anomalia escopo analitica
Detecção de anomalia
Marcar transações ou contas com comportamento diferente do resto, e dizer qual variável puxou cada uma para fora.
parâmetro	tipo	padrão	descrição
data	array	obrigatório	Um objeto por registro, com ao menos duas medidas numéricas (valor, quantidade, frequência).
parametros.contaminacao	número	0.03	Fração esperada de casos anômalos (0,001 a 0,3).
parametros.id_coluna	string	id	Coluna que identifica o registro.
`contaminacao` não é preferência: é a sua afirmação sobre quantos casos existem. Se marcar mais de 15%, a resposta avisa — cada marcação vira revisão manual ou conta bloqueada.
Cada anomalia volta com as três variáveis que mais se afastaram da mediana, em desvios.
Mínimo de 20 registros.
POST /api/v1/ai/v1/analitica/anomalia_grafo escopo analitica
Anomalia na rede
Analisar quem transaciona com quem e marcar nós com padrão incomum — o que não aparece olhando a transação isolada.
parâmetro	tipo	padrão	descrição
data[].origem	string	obrigatório	Nó de origem. Aceita `src`, `de`, `source`.
data[].destino	string	obrigatório	Nó de destino. Aceita `dst`, `para`, `target`.
data[].valor	número	opcional	Valor movimentado.
Um nó que recebe de muitos e envia para poucos é o padrão clássico de conta-laranja.
POST /api/v1/ai/v1/analitica/cesta escopo analitica
Cross-sell e cesta de compras
Descobrir quais itens são levados juntos com associação real.
parâmetro	tipo	padrão	descrição
data[].pedido	string	obrigatório	Identificador do pedido. Aceita `order_id`, `transacao`.
data[].item	string	obrigatório	O item. Aceita `produto`, `sku`.
parametros.suporte_minimo	inteiro	5	Quantas vezes o par precisa aparecer.
Ordenado por **lift**, não por confiança. Um item presente em 80% dos pedidos tem confiança alta com tudo e a regra parece forte sem dizer nada — lift 1 é independência, lift 3 é o item triplicando a chance do outro.
Lift abaixo de 0,8 significa que os itens **se evitam**: quem leva um tende a não levar o outro.
Mínimo de 20 pedidos distintos.
POST /api/v1/ai/v1/analitica/jornada escopo analitica
Jornada e atribuição por canal
Ver por onde o cliente passa, onde abandona, e quanto cada canal de fato contribui para a conversão.
parâmetro	tipo	padrão	descrição
data[].sessao	string	obrigatório	A jornada. Aceita `session_id`, `cliente`.
data[].etapa	string	obrigatório	A etapa ou canal. Aceita `canal`, `touchpoint`.
data[].ordem	número ou data	ordem de envio	Para ordenar a sequência.
data[].converteu	0 ou 1	opcional	1 na última linha da sessão que converteu.
Duas medidas, e elas respondem coisas diferentes. **`diferenca_pp`** é quantos pontos percentuais a mais converte quem passou pelo canal — legível e é o que ordena a lista, mas não é causal: pode haver seleção.
**`efeito_de_remocao_pct`** vem da cadeia de Markov: quanto a conversão cai ao tirar o canal. Mede o papel dele no caminho, mas dá efeito máximo a qualquer etapa por onde todos passam.
Por isso etapas presentes em 95% ou mais das jornadas são marcadas como funil e ficam **fora do crédito** — senão o checkout leva um terço da atribuição de marketing.
Mínimo de 20 sessões.
POST /api/v1/ai/v1/analitica/nps escopo analitica
NPS com intervalo de confiança
Calcular o NPS e saber o quanto se pode confiar nele.
parâmetro	tipo	padrão	descrição
data[].nota	0 a 10	obrigatório	Uma linha por resposta. Aceita `score`, `resposta`, `rating`.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/analitica/nps \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{"data": [{"nota": 10}, {"nota": 9}, {"nota": 7}, {"nota": 3}]}'
Resposta
{
  "dados": {"respostas": 1200, "descartadas_fora_de_0_a_10": 0},
  "nps": {"pontuacao": 23.7, "intervalo_95": [18.7, 28.6],
          "margem": 5.0, "classificacao": "bom"},
  "composicao": {"promotores": 601, "neutros": 238, "detratores": 361}
}
Com 30 respostas a margem é de **±27 pontos**; com 1.200 ela cai para ±5. Comparar o NPS deste mês com o do mês passado sem olhar a margem é comparar ruído — a resposta avisa quando a amostra não permite.
Promotor é 9-10, neutro 7-8, detrator 0-6.
Mínimo de 5 respostas válidas.
POST /api/v1/ai/v1/analitica/valor_de_vida escopo analitica
Valor de vida do cliente
Quanto cada cliente já valeu e quanto tende a valer, para decidir quanto se pode gastar para adquirir um novo.
parâmetro	tipo	padrão	descrição
data[].receita	número	obrigatório	Total já gasto. Aceita `valor`, `revenue`.
data[].meses_ativo	número	mediana da base	Há quantos meses é cliente.
parametros.retencao_mensal	0 a 1	deduzida da base	Fração que continua de um mês para o outro.
parametros.margem_pct	número	100	Margem sobre a receita.
parametros.meses_de_projecao	inteiro	24	Horizonte (1 a 120).
parametros.desconto_anual_pct	número	10	Valor do dinheiro no tempo.
As premissas voltam na resposta. Trocar a retenção muda o número mais que qualquer outra coisa — informe a sua se souber, e se não souber a resposta diz que foi deduzida.
A projeção é descontada mês a mês: ignorar o desconto infla o número justamente no horizonte longo.
Traz a concentração: quanto do valor está nos 20% maiores.
POST /api/v1/ai/v1/analitica/estoque escopo analitica
Ponto de reposição e lote
Estoque de segurança, ponto de reposição e lote econômico por item.
parâmetro	tipo	padrão	descrição
data[].item	string	obrigatório	Aceita `sku`, `produto`.
data[].demanda_diaria	número	obrigatório	Consumo médio por dia.
data[].prazo_dias	número	obrigatório	Prazo de entrega do fornecedor.
data[].desvio_demanda	número	30% da média	Desvio-padrão da demanda diária.
data[].custo_unitario	número	opcional	Para o lote econômico.
parametros.nivel_de_servico	número	0.95	0.80, 0.90, 0.95, 0.99…
O nível de serviço é **decisão de negócio**, não detalhe técnico: 99% em vez de 95% custa cerca de 40% mais estoque parado, e quem decide é quem paga por ele.
Sem `desvio_demanda` a resposta assume 30% da média **e avisa** — fingir variabilidade zero daria estoque de segurança zero, que é o pior conselho possível.
POST /api/v1/ai/v1/analitica/preco escopo analitica
Elasticidade e preço ótimo
Descobrir como a sua demanda responde ao preço e onde a receita e o lucro são máximos.
parâmetro	tipo	padrão	descrição
data[].preco	número	obrigatório	Preço praticado. Aceita `price`, `valor_unitario`.
data[].quantidade	número	obrigatório	Unidades vendidas naquele preço. Aceita `units`.
parametros.custo_unitario	número	0	Custo variável por unidade.
parametros.preco_atual	número	opcional	Para comparar com a recomendação.
A recomendação é **limitada à faixa de preços que você já praticou** (com 10% de margem). Fora dela a estimativa não vale, e a fórmula devolveria um número que parece tão confiável quanto os outros — quando a resposta bate na borda, ela diz isso.
Com `custo_unitario`, a recomendação passa a ser por **lucro**. Receita máxima e lucro máximo são pontos diferentes sempre que há custo variável.
Vem com R², erro-padrão e intervalo: uma elasticidade de −1,8 num R² de 0,08 é ruído com sinal de menos, e a resposta avisa.
Precisa de ao menos 3 preços distintos — sem variação de preço não há elasticidade a estimar.
POST /api/v1/ai/v1/analitica/agrupamento pode ser assíncronaescopo analitica

Agrupamento de clientes

Agrupar por similaridade e descrever o perfil médio de cada grupo.

parâmetro	tipo	padrão	descrição
parametros.grupos	inteiro	automático	2 a 12; vazio = escolher pela silhueta.
parametros.variaveis	array	recência, frequência, valor	Colunas a usar.

Modelos e estado

O que o servidor sabe fazer e como ele esta agora.

GET /api/v1/ai/v1/models

Modelos disponiveis

Descobrir o que da' para pedir, sem adivinhar nomes.

GET /api/v1/ai/v1/system/health

O servico esta de pe?

Sonda de monitoramento. Nao consome cota.