{"openapi":"3.1.0","info":{"title":"Abintel — API publica","version":"2.0.0","summary":"IA e analise de negocio por API, em infraestrutura propria.","description":"## Autenticacao\n\nToda chamada leva a sua credencial no cabecalho:\n\n    Authorization: Bearer <api_id>.<segredo>\n\nO `api_id` comeca com `ab_`. O segredo aparece **uma unica vez**, no momento em que\na credencial e' criada — nem o operador consegue recupera-lo depois, porque o que\nfica guardado e' um hash scrypt. Perdeu, gere outra credencial.\n\nClientes da versao anterior podem continuar usando os cabecalhos\n`X-Customer-Api-Id` e `X-Secret`; as duas formas valem.\n\n## Chamadas longas\n\nChamadas de GPU podem levar de segundos a minutos. Duas formas de esperar:\n\n* **Sincrona** (padrao): a resposta so volta quando o trabalho termina. Simples,\n  e o que quase todo mundo quer. Use timeout de cliente de pelo menos **180 s** —\n  timeout curto faz voce desistir de um trabalho que a placa ja comecou.\n* **Assincrona**: envie com `\"async\": true`, receba um `job_id` na hora e acompanhe\n  por `GET /v1/jobs/{job_id}` ou pelo fluxo de eventos em\n  `GET /v1/jobs/{job_id}/stream`. E' o caminho certo para lote e para transcricao\n  de audio longo.\n\n## Reenvio seguro\n\nUm pedido de GPU pode levar minutos. Se o seu cliente estourar o proprio timeout e\nreenviar, sem cuidado voce paga duas vezes e ocupa a placa duas vezes.\n\nMande um cabecalho `Idempotency-Key` com um valor unico por pedido — um UUID serve:\n\n    Idempotency-Key: 4f9c2a1e-7b3d-4c8a-9e21-0a5f6d8b3c74\n\nO que acontece no reenvio com a mesma chave:\n\n* se o primeiro pedido **ainda esta rodando**, voce recebe **409** com o `job_id`\n  para acompanhar, em vez de disparar um segundo trabalho;\n* se ele **ja terminou**, voce recebe a **mesma resposta**, com o cabecalho\n  `Idempotency-Replayed: true`. Nao consome cota e nao toca a placa.\n\nA chave vale por 24 horas e considera o corpo do pedido: reusar a mesma chave com\num conteudo diferente executa normalmente, em vez de devolver a resposta antiga —\nesse e' o erro mais comum de quem usa idempotencia pela primeira vez.\n\nResposta muito grande (imagem em base64, por exemplo) nao e' guardada para\nrepeticao; nesse caso o reenvio devolve o `job_id` para voce buscar o resultado.\n\n## Cache deterministico\n\nChamada com `temperature: 0` e' **deterministica por contrato**: a mesma entrada\ndevolve a mesma saida. Guardamos essa resposta por 24 horas e servimos as repeticoes\nsem tocar a placa.\n\nMedido na nossa carga real: 66% dos pedidos vem com temperatura 0, e 52,6% deles sao\nrepeticoes exatas — cerca de um terco do trabalho era refeito. Uma resposta em cache\nvolta em ~40 ms, contra segundos de geracao.\n\nComo saber que veio do cache: a resposta traz `do_cache: true`. Sem isso, uma latencia\nde 40 ms onde voce espera 4 s pareceria defeito.\n\n**Com amostragem nao cacheamos.** Se voce mandou `temperature` maior que zero, pediu\nvariacao — servir a mesma resposta seria quebrar o que voce contratou para economizar\nplaca nossa, e voce nao teria como saber. Se quiser cache mesmo assim, mande\n`\"cache\": true`; para desligar num pedido deterministico, `\"cache\": false`.\n\nA chave considera modelo, quantizacao, mensagens, teto de tokens e cada parametro de\namostragem. Mudou qualquer um, e' outro pedido.\n\n## Erros e limites\n\nErros vem sempre no mesmo formato, com um `codigo` estavel para o seu codigo tratar\ne uma `mensagem` para pessoas lerem:\n\n    {\"erro\": {\"codigo\": \"cota_mensal_esgotada\", \"mensagem\": \"...\"}}\n\n| HTTP | codigo | o que fazer |\n|---|---|---|\n| 401 | `credencial_invalida` | conferir api_id e segredo |\n| 403 | `rota_nao_permitida` | a rota nao esta no seu plano; fale conosco |\n| 403 | `credencial_inativa` | credencial desativada no painel |\n| 429 | `limite_por_minuto` | esperar o `Retry-After` e tentar de novo |\n| 429 | `limite_simultaneas` | reduzir chamadas em paralelo |\n| 429 | `cota_mensal_esgotada` | subir de plano ou esperar o proximo mes |\n| 404 | `nao_encontrado` | o job ou arquivo nao e' seu, ou nao existe |\n| 409 | `em_andamento` | mesmo `Idempotency-Key` ainda em execucao |\n| 502 | `upstream_indisponivel` | falha nossa; tente de novo com espera |\n\nTodo 429 traz `Retry-After` em segundos. Respeite-o: tentar em laco transforma o\nseu proprio limite numa tempestade que atrasa as suas outras chamadas.","contact":{"email":"contato@abintel.digital","url":"https://abintel.digital/docs"}},"servers":[{"url":"https://abintel.digital/api/v1/ai","description":"Producao"}],"security":[{"credencial":[]}],"tags":[{"name":"Texto e conversa","description":"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."},{"name":"Análise de texto","description":"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."},{"name":"Embeddings e busca semantica","description":"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."},{"name":"Audio e transcricao","description":"Transcricao com Whisper large-v3, com marcacao de tempo e deteccao de idioma."},{"name":"Sintese de voz","description":"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."},{"name":"Geracao de imagem","description":"SDXL-Turbo numa Tesla T4 dedicada a midia. Catalogo 1024x1024 em ~4 s."},{"name":"Visao computacional","description":"Descrever imagem, responder perguntas sobre ela e extrair texto."},{"name":"Arquivos","description":"Envie uma vez, use em varias chamadas. Arquivos expiram sozinhos."},{"name":"Acompanhamento de trabalho","description":"Para chamadas assincronas: acompanhar, aguardar e cancelar."},{"name":"Análise de negócio","description":"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."},{"name":"Modelos e estado","description":"O que o servidor sabe fazer e como ele esta agora."}],"paths":{"/v1/chat/completions":{"post":{"operationId":"post_v1_chat_completions","summary":"Conversa no formato OpenAI","description":"O caminho padrao para quase tudo: perguntas, resumo, extracao, classificacao, reescrita.\n\n`max_tokens` e' o que mais mexe no seu tempo de resposta e na sua cota: dobrar o teto costuma dobrar o tempo.\n\nCom `stream: true` os tokens chegam em `text/event-stream`.\n\nEscopo necessario na credencial: `llm`.","tags":["Texto e conversa"],"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"example":{"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}}}}},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Nome do modelo. Apelido desconhecido cai no modelo padrao do servidor em vez de dar erro.","example":"padrao do servidor"},"messages":{"type":"array","items":{},"description":"Lista de mensagens com `role` (system/user/assistant) e `content`."},"max_tokens":{"type":"integer","description":"Teto de tokens gerados. Menor e' mais rapido e mais barato.","example":"1024"},"temperature":{"type":"number","description":"0 e' deterministico; 0.7 e' criativo.","example":"0.7"},"stream":{"type":"boolean","description":"Devolve os tokens conforme saem, em SSE.","example":"false"}},"required":["messages"]}}}}}},"/v1/completions":{"post":{"operationId":"post_v1_completions","summary":"Completacao simples (formato legado)","description":"Compatibilidade com codigo antigo que usa `prompt` em vez de `messages`.\n\nEscopo necessario na credencial: `llm`.","tags":["Texto e conversa"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"O texto a completar."},"max_tokens":{"type":"integer","description":"Teto de tokens gerados.","example":"1024"}},"required":["prompt"]}}}}}},"/v1/llm/generate":{"post":{"operationId":"post_v1_llm_generate","summary":"Geracao nativa, com controle de job","description":"Quando voce quer o `job_id` para acompanhar progresso ou cancelar.\n\nEscopo necessario na credencial: `llm`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Texto e conversa"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"O texto de entrada."},"async":{"type":"boolean","description":"Retorna na hora com o job_id.","example":"false"},"priority":{"type":"integer","description":"0 e' a maior. Seu plano define o padrao.","example":"do plano"}},"required":["prompt"]}}}}}},"/api/generate":{"post":{"operationId":"post_api_generate","summary":"Geracao no formato Ollama","description":"Para quem ja tem cliente Ollama: nao muda uma linha de codigo.\n\nNomes de modelo do Ollama sao traduzidos para o modelo equivalente daqui; nao ha download de modelo pelo cliente.\n\nEscopo necessario na credencial: `llm`.","tags":["Texto e conversa"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Nome no estilo Ollama, ex.: `llama3.2`."},"prompt":{"type":"string","description":"O texto de entrada."}},"required":["model","prompt"]}}}}}},"/api/chat":{"post":{"operationId":"post_api_chat","summary":"Conversa no formato Ollama","description":"Mesmo caso acima, para o endpoint de chat do Ollama.\n\nEscopo necessario na credencial: `llm`.","tags":["Texto e conversa"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Nome no estilo Ollama."},"messages":{"type":"array","items":{},"description":"Mensagens da conversa."}},"required":["messages","model"]}}}}}},"/v1/texto":{"get":{"operationId":"get_v1_texto","summary":"Tarefas de texto disponíveis","description":"Descobrir o que dá para pedir e quais campos cada tarefa devolve.\n\nEscopo necessario na credencial: `llm`.","tags":["Análise de texto"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}}}},"/v1/texto/sentimento":{"post":{"operationId":"post_v1_texto_sentimento","summary":"Sentimento","description":"Classificar avaliações, chamados ou comentários como positivo, neutro ou negativo, com o trecho que justifica.\n\n**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.\n\nCada texto é uma geração, então um lote de 500 leva minutos. Use `async` e acompanhe pelo `job_id`.\n\nEscopo necessario na credencial: `llm`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Análise de texto"],"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"example":{"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"}]}}}},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"textos":{"type":"array","items":{},"description":"Lista de textos. Até 500 por chamada, 8.000 caracteres cada."},"async":{"type":"boolean","description":"Acima de algumas dezenas, use assíncrono.","example":"false"}},"required":["textos"]}}}}}},"/v1/texto/classificacao":{"post":{"operationId":"post_v1_texto_classificacao","summary":"Classificação por categoria","description":"Colocar cada texto numa das categorias que você definir.\n\nQuando nenhuma categoria serve, o modelo responde `outra` em vez de forçar uma errada.\n\nEscopo necessario na credencial: `llm`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Análise de texto"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"textos":{"type":"array","items":{},"description":"Lista de textos."},"categorias":{"type":"array","items":{},"description":"As opções possíveis, por exemplo entrega, produto, atendimento."}},"required":["categorias","textos"]}}}}}},"/v1/texto/resumo":{"post":{"operationId":"post_v1_texto_resumo","summary":"Resumo","description":"Resumir cada texto em uma ou duas frases, com o tema.\n\nEscopo necessario na credencial: `llm`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Análise de texto"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"textos":{"type":"array","items":{},"description":"Lista de textos."}},"required":["textos"]}}}}}},"/v1/texto/extracao":{"post":{"operationId":"post_v1_texto_extracao","summary":"Extração de campos","description":"Puxar campos estruturados de texto livre — valor, prazo, produto, o que você definir.\n\nEscopo necessario na credencial: `llm`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Análise de texto"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"textos":{"type":"array","items":{},"description":"Lista de textos."},"campos":{"type":"string","description":"Nome e significado de cada campo. Exemplo: {\"valor\": \"o valor em reais\", \"prazo\": \"o prazo citado\"}"}},"required":["campos","textos"]}}}}}},"/v1/embeddings":{"post":{"operationId":"post_v1_embeddings","summary":"Vetores no formato OpenAI","description":"Indexar documentos e transformar a pergunta do usuario em vetor.\n\n1.024 dimensoes. Mande em lote: cem textos numa chamada custam uma unidade de cota, cem chamadas custam cem.\n\nEscopo necessario na credencial: `embeddings`.","tags":["Embeddings e busca semantica"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Um texto ou uma lista deles. Lista e' muito mais eficiente."},"model":{"type":"string","description":"Apelido desconhecido cai no padrao.","example":"BAAI/bge-m3"}},"required":["input"]}}}}}},"/v1/rerank":{"post":{"operationId":"post_v1_rerank","summary":"Reordenar por relevancia","description":"Depois de recuperar 50 candidatos por vetor, escolher os 5 melhores. Melhora RAG mais que trocar de modelo de embedding.\n\nEscopo necessario na credencial: `embeddings`.","tags":["Embeddings e busca semantica"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"A pergunta."},"documents":{"type":"array","items":{},"description":"Os candidatos a reordenar."},"top_n":{"type":"integer","description":"Quantos devolver.","example":"todos"}},"required":["documents","query"]}}}}}},"/v1/audio/transcriptions":{"post":{"operationId":"post_v1_audio_transcriptions","summary":"Transcrever (formato OpenAI)","description":"Envio direto do arquivo, em multipart. O caminho mais simples.\n\nAudio longo e' o caso classico para `async`: uma hora de gravacao nao cabe num timeout de cliente confortavel.\n\n`srt` e `vtt` saem prontos para legenda.\n\nEscopo necessario na credencial: `asr`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Audio e transcricao"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"mp3, wav, m4a, ogg, flac, mp4."},"language":{"type":"string","description":"Codigo ISO. Vazio detecta sozinho.","example":"auto"},"response_format":{"type":"string","description":"`json`, `verbose_json`, `text`, `srt`, `vtt`.","example":"verbose_json"}},"required":["file"]}}}}}},"/v1/asr/transcribe":{"post":{"operationId":"post_v1_asr_transcribe","summary":"Transcrever por file_id ou URL","description":"Quando o audio ja esta no nosso armazenamento ou acessivel por URL.\n\nEscopo necessario na credencial: `asr`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Audio e transcricao"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string","description":"Devolvido por `POST /v1/files`."},"url":{"type":"string","description":"Alternativa ao file_id."}}}}}}}},"/v1/audio/speech":{"post":{"operationId":"post_v1_audio_speech","summary":"Falar um texto (formato OpenAI)","description":"Devolve os BYTES do audio, nao JSON — igual ao OpenAI, entao quem ja usa a biblioteca deles nao muda o codigo.\n\nTexto 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.\n\nDeclaramos so' `wav` e `pcm`. Devolver WAV rotulado de mp3 quebraria no seu lado sem deixar pista de onde.\n\nO cabecalho `X-Audio-Duration-S` traz a duracao do que veio.\n\nEscopo necessario na credencial: `voz`.","tags":["Sintese de voz"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","description":"Texto a falar. Ate 20.000 caracteres."},"voice":{"type":"string","description":"Veja `GET /v1/audio/voices`.","example":"pf_dora"},"idioma":{"type":"string","description":"`pt-br`, `en-us` ou `es`.","example":"pt-br"},"speed":{"type":"string","description":"Entre 0,5 e 2,0.","example":"1.0"},"response_format":{"type":"string","description":"`wav` ou `pcm`. Nao geramos mp3 nem opus.","example":"wav"}},"required":["input"]}}}}}},"/v1/audio/voices":{"get":{"operationId":"get_v1_audio_voices","summary":"Vozes disponiveis","description":"Quais vozes existem em cada idioma, e qual e' a padrao.\n\nEscopo necessario na credencial: `voz`.","tags":["Sintese de voz"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}}}},"/v1/images/generations":{"post":{"operationId":"post_v1_images_generations","summary":"Gerar imagem a partir de texto","description":"Foto de produto, banner, ilustracao.\n\n`b64_json` e' o caminho rapido: os bytes voltam na resposta e nada precisa ser buscado depois.\n\nMedido: 1024x1024 em ~5,5 s ponta a ponta, ~1,6 MB de PNG.\n\nEscopo necessario na credencial: `images`.","tags":["Geracao de imagem"],"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"example":{"created":1788694014,"model":"stabilityai/sdxl-turbo","seed":1833471805,"job_id":"job_5b44d28084834da8","data":[{"width":1024,"height":1024,"b64_json":"iVBORw0KGgoAAAANS..."}]}}}},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"A descricao do que gerar."},"n":{"type":"integer","description":"Quantas imagens.","example":"1"},"size":{"type":"string","description":"Ex.: `1024x1024`, `1216x640`.","example":"1024x1024"},"response_format":{"type":"string","description":"`b64_json` devolve os bytes; `url` devolve um link.","example":"url"},"seed":{"type":"integer","description":"Fixe para reproduzir a mesma imagem."}},"required":["prompt"]}}}}}},"/v1/vision/analyze":{"post":{"operationId":"post_v1_vision_analyze","summary":"Analisar uma imagem","description":"Descricao, pergunta sobre a imagem, leitura de contexto visual.\n\nEscopo necessario na credencial: `vision`.","tags":["Visao computacional"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string","description":"Imagem ja enviada."},"url":{"type":"string","description":"Alternativa ao file_id."},"prompt":{"type":"string","description":"O que voce quer saber.","example":"descreva a imagem"}}}}}}}},"/v1/vision/ocr":{"post":{"operationId":"post_v1_vision_ocr","summary":"Extrair todo o texto de uma imagem","description":"Documento fotografado, print de tela, placa, formulario.\n\nEscopo necessario na credencial: `vision`.","tags":["Visao computacional"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string","description":"Imagem ja enviada."},"url":{"type":"string","description":"Alternativa ao file_id."}}}}}}}},"/v1/files":{"post":{"operationId":"post_v1_files","summary":"Enviar arquivo","description":"Audio para transcrever, imagem para analisar.\n\nEscopo necessario na credencial: `files`.","tags":["Arquivos"],"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"example":{"id":"file_9c1e...","bytes":20971520,"mime":"audio/wav"}}}},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"O conteudo, em multipart."}},"required":["file"]}}}}}},"/v1/files/{file_id}":{"get":{"operationId":"get_v1_files_file_id","summary":"Baixar arquivo","description":"Buscar um resultado que ficou guardado.\n\nEscopo necessario na credencial: `files`.","tags":["Arquivos"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador do recurso (file_id)."}]},"delete":{"operationId":"delete_v1_files_file_id","summary":"Apagar agora","description":"Nao esperar a expiracao — util para dado sensivel.\n\nEscopo necessario na credencial: `files`.","tags":["Arquivos"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador do recurso (file_id)."}]}},"/v1/files/{file_id}/meta":{"get":{"operationId":"get_v1_files_file_id_meta","summary":"Dados do arquivo","description":"Tamanho, tipo e validade, sem baixar o conteudo.\n\nEscopo necessario na credencial: `files`.","tags":["Arquivos"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador do recurso (file_id)."}]}},"/v1/jobs/{job_id}":{"get":{"operationId":"get_v1_jobs_job_id","summary":"Consultar um trabalho","description":"Saber se terminou e pegar o resultado.\n\nEscopo necessario na credencial: `jobs`.","tags":["Acompanhamento de trabalho"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador do recurso (job_id)."}]},"delete":{"operationId":"delete_v1_jobs_job_id","summary":"Cancelar","description":"Trabalho na fila sai na hora; em execucao para no proximo ponto seguro.\n\nEscopo necessario na credencial: `jobs`.","tags":["Acompanhamento de trabalho"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador do recurso (job_id)."}]}},"/v1/jobs/{job_id}/wait":{"get":{"operationId":"get_v1_jobs_job_id_wait","summary":"Aguardar ate terminar","description":"Long-poll: uma chamada so, sem laco de consulta do seu lado.\n\nEscopo necessario na credencial: `jobs`.","tags":["Acompanhamento de trabalho"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador do recurso (job_id)."}]}},"/v1/jobs/{job_id}/stream":{"get":{"operationId":"get_v1_jobs_job_id_stream","summary":"Acompanhar em tempo real","description":"Eventos SSE com progresso e, na geracao de texto, os tokens.\n\nEscopo necessario na credencial: `jobs`.","tags":["Acompanhamento de trabalho"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador do recurso (job_id)."}]}},"/v1/jobs":{"get":{"operationId":"get_v1_jobs","summary":"Listar seus trabalhos recentes","description":"Auditoria e depuracao do seu lado.\n\nA lista traz apenas os seus trabalhos.\n\nEscopo necessario na credencial: `jobs`.","tags":["Acompanhamento de trabalho"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}}}},"/v1/analitica":{"get":{"operationId":"get_v1_analitica","summary":"Análises disponíveis","description":"Descobrir o que dá para pedir e quais colunas cada uma exige.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}}}},"/v1/analitica/features":{"post":{"operationId":"post_v1_analitica_features","summary":"Extrato para tabela de cliente","description":"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.\n\nA saída entra **direto** em `/rfm`, `/churn`, `/valor_de_vida` e `/agrupamento`, sem retrabalho.\n\nA 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.\n\nCliente de compra única fica com intervalo `null`, não zero — zero inflaria a regularidade de quem comprou uma vez e sumiu.\n\nValor negativo conta no total e **não** na frequência, senão quem comprou e devolveu viraria cliente frequente.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"example":{"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}]}}}},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parametros":{"type":"object","properties":{"marco":{"type":"string","format":"date","description":"Referência para a recência.","example":"última transação da base"}}},"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"customer_id":{"type":"string","description":"Quem comprou. Aceita `cliente`, `id_cliente`."},"data":{"type":"string","format":"date","description":"Quando. Aceita `date`, `data_compra`."},"valor":{"type":"number","description":"Quanto. Valor negativo é tratado como devolução."}},"required":["customer_id","data"]}}},"required":["data"]}}}}}},"/v1/analitica/churn":{"post":{"operationId":"post_v1_analitica_churn","summary":"Risco de cancelamento","description":"Estimar quem vai cancelar, com os fatores que mais pesam e uma ação sugerida por faixa de risco.\n\nRegistros sem a coluna de rótulo **também são pontuados** — são justamente os que você quer prever.\n\nValor ausente é imputado pela mediana, e a resposta diz quantos foram, para você não confundir estimativa com medição.\n\nTeto de 100.000 registros por chamada.\n\nEscopo necessario na credencial: `analitica`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"example":{"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}]}}}},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"churned":{"type":"integer","enum":[0,1],"description":"1 = cancelou, 0 = ficou. Ao menos 10 registros rotulados; quem vier sem rótulo é pontuado."}},"required":["churned"]}},"async":{"type":"boolean","description":"Volume grande: receba o job_id na hora.","example":"false"}},"required":["data"]}}}}}},"/v1/analitica/risco_credito":{"post":{"operationId":"post_v1_analitica_risco_credito","summary":"Risco de crédito","description":"Estimar inadimplência e sugerir política de limite.\n\nEscopo necessario na credencial: `analitica`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"inadimplente":{"type":"integer","enum":[0,1],"description":"1 = inadimpliu, 0 = pagou."}},"required":["inadimplente"]}}},"required":["data"]}}}}}},"/v1/analitica/propensao":{"post":{"operationId":"post_v1_analitica_propensao","summary":"Propensão a converter","description":"Compra, resposta a campanha ou upgrade — a coluna a prever é sua.\n\nEscopo necessario na credencial: `analitica`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"parametros":{"type":"object","properties":{"rotulo":{"type":"string","description":"Nome da coluna 0/1 a prever.","example":"converteu"}}}}}}}}}},"/v1/analitica/rfm":{"post":{"operationId":"post_v1_analitica_rfm","summary":"Segmentação RFM","description":"Classificar por recência, frequência e valor, e nomear o segmento.\n\nRecência é invertida: quem comprou há menos tempo recebe nota maior.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parametros":{"type":"object","properties":{"quintis":{"type":"integer","description":"Faixas por dimensão (3 a 10).","example":"5"}}},"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"recencia":{"type":"number","description":"Dias desde a última compra."},"frequencia":{"type":"number","description":"Compras no período."},"valor":{"type":"number","description":"Total gasto."}},"required":["recencia","frequencia","valor"]}}},"required":["data"]}}}}}},"/v1/analitica/previsao":{"post":{"operationId":"post_v1_analitica_previsao","summary":"Previsão de série temporal","description":"Prever receita, custo, unidades ou qualquer série com data e valor, com intervalo de confiança.\n\nCompara 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.\n\nA 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.\n\nMínimo de 8 períodos.\n\nTransações na mesma data são somadas — mande agregado ou bruto, os dois funcionam.\n\nEscopo necessario na credencial: `analitica`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parametros":{"type":"object","properties":{"horizonte":{"type":"integer","description":"Quantos períodos prever (1 a 36).","example":"3"},"origens":{"type":"integer","description":"Pontos de validação temporal.","example":"4"}}},"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"data":{"type":"string","format":"date","description":"A data do período. Aceita `date`, `periodo`, `ds`."},"valor":{"type":"number","description":"O valor. Aceita `receita`, `custo`, `unidades`."}},"required":["data","valor"]}}},"required":["data"]}}}}}},"/v1/analitica/anomalia":{"post":{"operationId":"post_v1_analitica_anomalia","summary":"Detecção de anomalia","description":"Marcar transações ou contas com comportamento diferente do resto, e dizer qual variável puxou cada uma para fora.\n\n`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.\n\nCada anomalia volta com as três variáveis que mais se afastaram da mediana, em desvios.\n\nMínimo de 20 registros.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{},"description":"Um objeto por registro, com ao menos duas medidas numéricas (valor, quantidade, frequência)."},"parametros":{"type":"object","properties":{"contaminacao":{"type":"number","description":"Fração esperada de casos anômalos (0,001 a 0,3).","example":"0.03"},"id_coluna":{"type":"string","description":"Coluna que identifica o registro.","example":"id"}}}},"required":["data"]}}}}}},"/v1/analitica/anomalia_grafo":{"post":{"operationId":"post_v1_analitica_anomalia_grafo","summary":"Anomalia na rede","description":"Analisar quem transaciona com quem e marcar nós com padrão incomum — o que não aparece olhando a transação isolada.\n\nUm nó que recebe de muitos e envia para poucos é o padrão clássico de conta-laranja.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"origem":{"type":"string","description":"Nó de origem. Aceita `src`, `de`, `source`."},"destino":{"type":"string","description":"Nó de destino. Aceita `dst`, `para`, `target`."},"valor":{"type":"number","description":"Valor movimentado."}},"required":["origem","destino"]}}},"required":["data"]}}}}}},"/v1/analitica/cesta":{"post":{"operationId":"post_v1_analitica_cesta","summary":"Cross-sell e cesta de compras","description":"Descobrir quais itens são levados juntos com associação real.\n\nOrdenado 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.\n\nLift abaixo de 0,8 significa que os itens **se evitam**: quem leva um tende a não levar o outro.\n\nMínimo de 20 pedidos distintos.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parametros":{"type":"object","properties":{"suporte_minimo":{"type":"integer","description":"Quantas vezes o par precisa aparecer.","example":"5"}}},"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"pedido":{"type":"string","description":"Identificador do pedido. Aceita `order_id`, `transacao`."},"item":{"type":"string","description":"O item. Aceita `produto`, `sku`."}},"required":["pedido","item"]}}},"required":["data"]}}}}}},"/v1/analitica/jornada":{"post":{"operationId":"post_v1_analitica_jornada","summary":"Jornada e atribuição por canal","description":"Ver por onde o cliente passa, onde abandona, e quanto cada canal de fato contribui para a conversão.\n\nDuas 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.\n\n**`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.\n\nPor 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.\n\nMínimo de 20 sessões.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"sessao":{"type":"string","description":"A jornada. Aceita `session_id`, `cliente`."},"etapa":{"type":"string","description":"A etapa ou canal. Aceita `canal`, `touchpoint`."},"ordem":{"oneOf":[{"type":"number"},{"type":"string"}],"description":"Para ordenar a sequência.","example":"ordem de envio"},"converteu":{"type":"integer","enum":[0,1],"description":"1 na última linha da sessão que converteu."}},"required":["sessao","etapa"]}}},"required":["data"]}}}}}},"/v1/analitica/nps":{"post":{"operationId":"post_v1_analitica_nps","summary":"NPS com intervalo de confiança","description":"Calcular o NPS e saber o quanto se pode confiar nele.\n\nCom 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.\n\nPromotor é 9-10, neutro 7-8, detrator 0-6.\n\nMínimo de 5 respostas válidas.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"example":{"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}}}}},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"nota":{"type":"integer","minimum":0,"maximum":10,"description":"Uma linha por resposta. Aceita `score`, `resposta`, `rating`."}},"required":["nota"]}}},"required":["data"]}}}}}},"/v1/analitica/valor_de_vida":{"post":{"operationId":"post_v1_analitica_valor_de_vida","summary":"Valor de vida do cliente","description":"Quanto cada cliente já valeu e quanto tende a valer, para decidir quanto se pode gastar para adquirir um novo.\n\nAs 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.\n\nA projeção é descontada mês a mês: ignorar o desconto infla o número justamente no horizonte longo.\n\nTraz a concentração: quanto do valor está nos 20% maiores.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parametros":{"type":"object","properties":{"retencao_mensal":{"type":"number","minimum":0,"maximum":1,"description":"Fração que continua de um mês para o outro.","example":"deduzida da base"},"margem_pct":{"type":"number","description":"Margem sobre a receita.","example":"100"},"meses_de_projecao":{"type":"integer","description":"Horizonte (1 a 120).","example":"24"},"desconto_anual_pct":{"type":"number","description":"Valor do dinheiro no tempo.","example":"10"}}},"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"receita":{"type":"number","description":"Total já gasto. Aceita `valor`, `revenue`."},"meses_ativo":{"type":"number","description":"Há quantos meses é cliente.","example":"mediana da base"}},"required":["receita"]}}},"required":["data"]}}}}}},"/v1/analitica/estoque":{"post":{"operationId":"post_v1_analitica_estoque","summary":"Ponto de reposição e lote","description":"Estoque de segurança, ponto de reposição e lote econômico por item.\n\nO 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.\n\nSem `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.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parametros":{"type":"object","properties":{"nivel_de_servico":{"type":"number","description":"0.80, 0.90, 0.95, 0.99…","example":"0.95"}}},"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"item":{"type":"string","description":"Aceita `sku`, `produto`."},"demanda_diaria":{"type":"number","description":"Consumo médio por dia."},"prazo_dias":{"type":"number","description":"Prazo de entrega do fornecedor."},"desvio_demanda":{"type":"number","description":"Desvio-padrão da demanda diária.","example":"30% da média"},"custo_unitario":{"type":"number","description":"Para o lote econômico."}},"required":["item","demanda_diaria","prazo_dias"]}}},"required":["data"]}}}}}},"/v1/analitica/preco":{"post":{"operationId":"post_v1_analitica_preco","summary":"Elasticidade e preço ótimo","description":"Descobrir como a sua demanda responde ao preço e onde a receita e o lucro são máximos.\n\nA 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.\n\nCom `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.\n\nVem 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.\n\nPrecisa de ao menos 3 preços distintos — sem variação de preço não há elasticidade a estimar.\n\nEscopo necessario na credencial: `analitica`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parametros":{"type":"object","properties":{"custo_unitario":{"type":"number","description":"Custo variável por unidade.","example":"0"},"preco_atual":{"type":"number","description":"Para comparar com a recomendação."}}},"data":{"type":"array","description":"Um objeto por registro.","items":{"type":"object","properties":{"preco":{"type":"number","description":"Preço praticado. Aceita `price`, `valor_unitario`."},"quantidade":{"type":"number","description":"Unidades vendidas naquele preço. Aceita `units`."}},"required":["preco","quantidade"]}}},"required":["data"]}}}}}},"/v1/analitica/agrupamento":{"post":{"operationId":"post_v1_analitica_agrupamento","summary":"Agrupamento de clientes","description":"Agrupar por similaridade e descrever o perfil médio de cada grupo.\n\nEscopo necessario na credencial: `analitica`.\n\nPode ser assincrona: envie `\"async\": true` e acompanhe pelo `job_id`.","tags":["Análise de negócio"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"parametros":{"type":"object","properties":{"grupos":{"type":"integer","description":"2 a 12; vazio = escolher pela silhueta.","example":"automático"},"variaveis":{"type":"array","items":{},"description":"Colunas a usar.","example":"recência, frequência, valor"}}}}}}}}}},"/v1/models":{"get":{"operationId":"get_v1_models","summary":"Modelos disponiveis","description":"Descobrir o que da' para pedir, sem adivinhar nomes.","tags":["Modelos e estado"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}}}},"/v1/system/health":{"get":{"operationId":"get_v1_system_health","summary":"O servico esta de pe?","description":"Sonda de monitoramento. Nao consome cota.","tags":["Modelos e estado"],"responses":{"200":{"description":"Sucesso."},"401":{"$ref":"#/components/responses/CredencialInvalida"},"403":{"$ref":"#/components/responses/Proibido"},"404":{"$ref":"#/components/responses/NaoEncontrado"},"409":{"$ref":"#/components/responses/EmAndamento"},"429":{"$ref":"#/components/responses/LimiteExcedido"},"503":{"$ref":"#/components/responses/PlataformaOcupada"}}}}},"components":{"securitySchemes":{"credencial":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <api_id>.<segredo>`. O segredo aparece uma unica vez, quando a credencial e' criada."}},"schemas":{"Erro":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string","description":"Estavel: trate por ele."},"mensagem":{"type":"string","description":"Para pessoas; pode mudar."}},"required":["codigo","mensagem"]}},"required":["erro"]}},"responses":{"CredencialInvalida":{"description":"Credencial ausente, invalida ou vencida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"example":{"erro":{"codigo":"credencial_invalida","mensagem":"Credencial invalida."}}}}},"Proibido":{"description":"A rota nao esta liberada para esta credencial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"example":{"erro":{"codigo":"rota_nao_permitida","mensagem":"A rota '/v1/x' nao esta liberada."}}}}},"NaoEncontrado":{"description":"O recurso nao existe ou nao e' seu.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"example":{"erro":{"codigo":"nao_encontrado","mensagem":"Nao encontrei 'job_abc'."}}}}},"EmAndamento":{"description":"Mesmo `Idempotency-Key` ainda em execucao.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"example":{"erro":{"codigo":"em_andamento","mensagem":"Um pedido com esta chave ainda esta em execucao."}}}}},"LimiteExcedido":{"description":"Limite do seu plano. Respeite o `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"example":{"erro":{"codigo":"limite_por_minuto","mensagem":"Limite de 120 chamadas por minuto."}}}}},"PlataformaOcupada":{"description":"Saturacao NOSSA, nao limite seu. Respeite o `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"},"example":{"erro":{"codigo":"plataforma_ocupada","mensagem":"A plataforma esta com todos os recursos ocupados."}}}}}}}}