L17 models_
Documentação da api

Uma chamada, várias decisões

Você envia um texto (state) ou uma gravação (audio) e as perguntas com as opções possíveis (questions). Cada produto é um modelo: troque de produto mudando o campo model. O formato é o mesmo para todos.

base url: https://api.logo17.com.br

Autenticação

Crie uma chave no painel e envie no cabeçalho Authorization: Bearer l17_…. Cada chave pertence a um projeto, e o consumo aparece separado por projeto. A chave é mostrada uma única vez: guarde num cofre de segredos.

POST /v1/decide

Responde todas as perguntas do pedido numa única passada do modelo.

curl
curl https://api.logo17.com.br/v1/decide \
  -H "Authorization: Bearer $L17_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "l17-decide",
    "state": {"canal": "WhatsApp", "mensagem": "Fui cobrado duas vezes na fatura..."},
    "questions": {
      "motivo": {"type": "choice", "instructions": "Qual o motivo do contato?",
                 "criteria": {"cobranca": "problema com cobrança ou fatura",
                              "tecnico": "problema técnico",
                              "informacao": "dúvida ou pedido de informação"}},
      "irritacao": {"type": "score", "instructions": "Quão irritado o cliente está?",
                    "criteria": ["calmo", "incomodado", "irritado", "furioso"]},
      "quer_cancelar": {"type": "noul", "instructions": "O cliente ameaça cancelar o serviço"}
    }
  }'
python
import httpx

r = httpx.post("https://api.logo17.com.br/v1/decide",
               headers={"Authorization": f"Bearer {L17_API_KEY}"},
               json={"model": "l17-decide", "state": texto, "questions": perguntas})
r.raise_for_status()
for nome, resposta in r.json()["answers"].items():
    print(nome, resposta)
campotipodescrição
modelstringproduto (ver Produtos). Padrão: l17-decide
statetexto | objeto | listao que o modelo lê. Objetos viram linhas "chave: valor"
audioobjetono lugar de state: uma gravação, transcrita antes das perguntas (ver Áudio)
questionsobjetoperguntas por nome; cada uma com type, instructions e criteria

POST /v1/classify

Uma pergunta só: qual tabulação da sua lista melhor descreve o atendimento. Mande o ticket, a conversa de WhatsApp ou a transcrição da chamada, e a lista de tabulações com código, nome e descrição. Volta a escolhida, o ranking e se vale mandar para revisão humana.

requisiçãoPOST /v1/classify
{
  "model": "l17-qualifica",
  "channel": "whatsapp",
  "state": [
    {"role": "customer", "text": "fui cobrado duas vezes na fatura de setembro"},
    {"role": "agent",  "text": "vou abrir a contestação e o estorno sai em 5 dias"}
  ],
  "labels": [
    {"code": "FAT-02", "name": "Contestação de cobrança", "description": "cobrança indevida ou em duplicidade",
     "category": "Financeiro > Fatura"},
    {"code": "CAN-01", "name": "Pedido de cancelamento", "description": "cliente quer encerrar o contrato"},
    {"code": "TEC-03", "name": "Sem conexão", "description": "internet ou linha sem funcionar"}
  ],
  "top_k": 3
}
200 OK
{
  "model": "l17-qualifica",
  "label": {"code": "FAT-02", "name": "Contestação de cobrança", "probability": 0.87},
  "ranking": [
    {"code": "FAT-02", "name": "Contestação de cobrança", "probability": 0.87},
    {"code": "CAN-01", "name": "Pedido de cancelamento", "probability": 0.08},
    {"code": "TEC-03", "name": "Sem conexão", "probability": 0.02}
  ],
  "none": 0.03,
  "confidence": 0.71,
  "review": false,
  "usage": {"input_tokens": 142, "output_tokens": 0}
}
statetexto solto ou lista de turnos {role, text}; os turnos viram "role: text", uma linha cada
channelopcional: ticket, whatsapp, call… ajuda o modelo a ler o texto
labelsas tabulações: itens {code, name, description, category}; a descrição é o que mais pesa. category é opcional: "Financeiro > Fatura" ou ["Financeiro", "Fatura"], até 4 níveis
categoriesopcional: descrição de cada categoria, {"Financeiro": "fatura, cobrança e pagamentos"}
modeauto (padrão): flat quando cabem numa escolha só (até 254), hierarchical quando não cabem · flat · hierarchical
beamna hierarquia, quantas categorias seguem abertas em cada nível (1 a 5, padrão 2)
top_kquantas tabulações voltam no ranking (1 a 20, padrão 3)
review_thresholdabaixo desta probabilidade, review = true (0 a 1, padrão 0,5)
include_noneacrescenta a opção "nenhuma se aplica" (padrão true); se ela vencer, label = null e review = true
instructionsopcional: troca a pergunta padrão, "Qual tabulação melhor descreve este atendimento?"

Lista ou hierarquia. Em flat, o modelo escolhe entre todas as tabulações de uma vez, com a categoria no texto de cada uma. Em hierarchical, escolhe a categoria e desce nível a nível (uma passada do modelo por nível), mantendo as beam categorias mais prováveis abertas; a probabilidade é o produto do caminho. Listas de até 254 tabulações acertam mais em flat; acima disso, agrupe em categorias. Cada item do ranking traz a category.

Cobrança igual à do /v1/decide: os tokens de entrada (atendimento + lista de tabulações, somados em todos os níveis) viram créditos, 1 a cada 1.000 tokens ou fração. Textos muito longos são cortados no fim; em chamadas de mais de ~30 minutos, mande a parte que importa.

Áudio: decidir direto sobre a ligação novo

Nos dois endpoints, troque state por audio: a gravação é transcrita em português e o texto vira o state das suas perguntas (ou o atendimento do /v1/classify). Se a gravação tem um canal por falante, como costuma vir do PABX, diga quem está em cada canal e a transcrição sai separada por falante, na ordem em que cada um falou.

curl
curl https://api.logo17.com.br/v1/decide \
  -H "Authorization: Bearer $L17_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "l17-decide",
    "audio": {"format": "mp3", "data": "<arquivo em base64>",
              "channels": {"0": "atendente", "1": "cliente"}},
    "include_transcript": true,
    "questions": {
      "motivo": {"type": "choice", "instructions": "Qual o motivo da ligação?",
                 "criteria": {"cancelamento": "cliente quer cancelar o serviço",
                              "tecnico": "problema técnico", "cobranca": "dúvida sobre fatura"}},
      "irritado": {"type": "noul", "instructions": "O cliente demonstra irritação"}
    }
  }'
python
import base64, httpx

audio = {"format": "wav", "data": base64.b64encode(open("ligacao.wav", "rb").read()).decode(),
         "channels": {"0": "atendente", "1": "cliente"}}
r = httpx.post("https://api.logo17.com.br/v1/classify", timeout=180,
               headers={"Authorization": f"Bearer {L17_API_KEY}"},
               json={"audio": audio, "labels": tabulacoes, "include_transcript": True})
print(r.json()["label"], r.json()["usage"]["audio_minutes_billed"])
campotipodescrição
audio.datastringo arquivo em base64, até 20 MB (antes da codificação)
audio.formatstringwav, mp3, ogg / opus (áudio do WhatsApp), m4a, flac ou webm; de 8 a 48 kHz, mono ou estéreo
audio.channelsobjetoopcional: quem fala em cada canal de uma gravação estéreo, {"0": "atendente", "1": "cliente"} (0 = esquerdo). Sem ele, os canais são misturados e o texto sai sem falantes
include_transcriptbooleanoopcional: devolve a transcrição em transcript (text e turns com role, start em segundos e text)

Limites e tempo. Até 30 minutos por chamada. A transcrição leva alguns segundos por ligação: use um timeout de pelo menos 3 minutos para gravações longas e o Idempotency-Key se a sua integração repete chamadas. A resposta traz usage.audio_seconds e usage.audio_minutes_billed.

Cobrança. 5 créditos por minuto de áudio, contando o minuto cheio (61 segundos = 2 minutos), mais os créditos normais dos tokens do texto transcrito com as perguntas. Uma ligação de 3 minutos com 3 perguntas fica em torno de 16 créditos. Áudio que não decodifica ou sem fala não é cobrado.

Privacidade. O áudio é usado só para a transcrição desta chamada e não é guardado; com include_transcript desligado, o texto também não volta para você. Avise o cliente sobre a gravação e o uso, como pede a LGPD.

Tipos de pergunta

choice
criteria
objeto {"opção": "descrição"}, de 2 a 255 opções
resposta
choice, probabilities, confidence
score
criteria
lista de 2 a 10 níveis, em ordem
resposta
score (média ponderada dos níveis, a partir de 0), probabilities, legend, confidence
noul
criteria
opcional {"true": …, "false": …}
resposta
noul: probabilidade de verdadeiro, de 0 a 1

A descrição de cada opção é o que o modelo lê: descrições claras dão respostas melhores.

Resposta

200 OKX-L17-Credits · X-L17-Cost · X-L17-Balance
{
  "model": "l17-decide",
  "answers": {
    "motivo":        {"type": "choice", "choice": "cobranca", "confidence": 0.67,
                      "probabilities": {"cobranca": 0.89, "tecnico": 0.03, "informacao": 0.08}},
    "irritacao":     {"type": "score", "score": 2.64, "confidence": 0.44,
                      "probabilities": {"0": 0.02, "1": 0.04, "2": 0.24, "3": 0.70},
                      "legend": {"0": "calmo", "1": "incomodado", "2": "irritado", "3": "furioso"}},
    "quer_cancelar": {"type": "noul", "noul": 0.92}
  },
  "usage": {"input_tokens": 386, "output_tokens": 0}
}

confidence = 1 − entropia normalizada da distribuição: alta quando uma opção domina. Os cabeçalhos X-L17-Credits e X-L17-Credits-Remaining trazem os créditos da chamada e os que sobram no ciclo; X-L17-Cost e X-L17-Balance, o que saiu do saldo em reais (só excedente ou uso avulso) e o saldo restante.

Erros e cobrança

Cada resposta 200 consome 1 crédito a cada 1.000 tokens de entrada (state + perguntas), no mínimo 1: uma mensagem de WhatsApp com a lista de tabulações é 1 crédito; uma transcrição de 2.500 tokens, 3. Com áudio, somam-se 5 créditos por minuto (minuto cheio). Os créditos saem da cota mensal do plano; o que passar é cobrado do saldo em reais ao preço de excedente (preços). Erros não consomem créditos.

400corpo inválido, sem state/questions ou com audio malformado (formato, base64, canais)
401chave ausente, inválida ou revogada
402sem créditos no plano e sem saldo em reais
404produto (model) inexistente ou indisponível
409pedido com a mesma Idempotency-Key ainda em processamento
422pergunta inválida (o corpo diz qual e por quê), áudio que não decodifica ou sem fala, ou Idempotency-Key já usada com outro pedido
502modelo indisponível no momento; tente de novo

Repetir sem cobrar duas vezes: Idempotency-Key

Se a sua integração repete chamadas quando a rede falha, envie o cabeçalho Idempotency-Key com um identificador único do pedido (até 100 caracteres, ex. o id do atendimento). Repetir o mesmo pedido com a mesma chave em até 24 horas devolve a resposta original, com o cabeçalho Idempotent-Replayed: true, sem chamar o modelo e sem cobrar de novo. Se a chamada falhou, a mesma chave pode ser usada na nova tentativa.

curl https://api.logo17.com.br/v1/classify \
  -H "Authorization: Bearer l17_..." \
  -H "Idempotency-Key: atendimento-83127" \
  -d @pedido.json
Produtos

Produtos

Cada produto é um modelo do catálogo, escolhido pelo campo model, na chamada indicada ao lado dele.

L17 Decide

"model": "l17-decide" POST /v1/decide
disponível
1 crédito por 1.000 tokens de entrada · saída grátis

Modelo genérico: responde qualquer pergunta tipada sobre textos em português, com a probabilidade de cada opção.

  • →Triagem de mensagens e tickets
  • →Classificação de avaliações e reclamações
  • →Roteamento de pedidos por intenção
  • →Filtro antes de chamar um LLM caro
ver pedido de exemplo
{
  "state": {
    "canal": "WhatsApp",
    "mensagem": "Já é a terceira vez que eu reclamo! Fui cobrado duas vezes na fatura de setembro e ninguém resolve. Se não estornarem até sexta eu cancelo o plano e vou no Procon."
  },
  "questions": {
    "motivo": {
      "type": "choice",
      "instructions": "Qual o motivo do contato?",
      "criteria": {
        "cobranca": "problema com cobrança ou fatura",
        "tecnico": "problema técnico ou falha no serviço",
        "entrega": "atraso ou problema na entrega",
        "informacao": "dúvida ou pedido de informação"
      }
    },
    "irritacao": {
      "type": "score",
      "instructions": "Quão irritado o cliente está?",
      "criteria": [
        "calmo",
        "um pouco incomodado",
        "irritado",
        "furioso"
      ]
    },
    "quer_cancelar": {
      "type": "noul",
      "instructions": "O cliente ameaça cancelar o serviço"
    },
    "elogio": {
      "type": "noul",
      "instructions": "O cliente está elogiando o atendimento"
    }
  }
}

L17 Qualifica

"model": "l17-qualifica" POST /v1/classify
disponível
1 crédito por 1.000 tokens de entrada · saída grátis

Tabulação automática de atendimentos: escolhe na sua lista de tabulações a que melhor descreve o ticket, a conversa de WhatsApp ou a chamada transcrita.

  • →Tabulação automática no fim do atendimento
  • →Sugestão das 3 tabulações mais prováveis para o agente
  • →Auditoria: comparar com o que o agente marcou
  • →Relatórios de motivo de contato confiáveis
ver pedido de exemplo
{
  "channel": "whatsapp",
  "state": [
    {
      "role": "customer",
      "text": "Boa tarde, veio cobrado duas vezes o plano na fatura de setembro."
    },
    {
      "role": "agent",
      "text": "Verifiquei aqui, houve duplicidade. Vou abrir a contestação e o estorno sai em até 5 dias úteis."
    },
    {
      "role": "customer",
      "text": "Ok, obrigado."
    }
  ],
  "labels": [
    {
      "code": "FAT-01",
      "name": "Segunda via de fatura",
      "description": "cliente pede boleto, código de barras ou cópia da fatura"
    },
    {
      "code": "FAT-02",
      "name": "Contestação de cobrança",
      "description": "cobrança indevida, em duplicidade ou valor diferente do contratado"
    },
    {
      "code": "CAN-01",
      "name": "Pedido de cancelamento",
      "description": "cliente quer encerrar o contrato ou o serviço"
    },
    {
      "code": "TEC-03",
      "name": "Sem conexão",
      "description": "internet, linha ou serviço sem funcionar"
    },
    {
      "code": "INF-01",
      "name": "Informação sobre planos",
      "description": "dúvidas sobre preços, planos ou ofertas"
    }
  ],
  "top_k": 3
}

L17 Atendimento

"model": "l17-atendimento" POST /v1/decide
em breve
em breve

Especializado em atendimento ao cliente: triagem de tickets, chats e WhatsApp e monitoria de ligações transcritas.

  • →Roteamento automático por motivo e urgência
  • →Fila prioritária para risco de cancelamento e Procon
  • →Monitoria de 100% das ligações transcritas
  • →Indicadores de qualidade por agente
ver pedido de exemplo
{
  "state": {
    "canal": "WhatsApp",
    "mensagem": "Já é a terceira vez que eu reclamo! Fui cobrado duas vezes na fatura de setembro e ninguém resolve. Se não estornarem até sexta eu cancelo o plano e vou no Procon."
  },
  "questions": {
    "motivo": {
      "type": "choice",
      "instructions": "Qual o motivo do contato?",
      "criteria": {
        "cobranca": "problema com cobrança ou fatura",
        "tecnico": "problema técnico ou falha no serviço",
        "entrega": "atraso ou problema na entrega",
        "informacao": "dúvida ou pedido de informação"
      }
    },
    "irritacao": {
      "type": "score",
      "instructions": "Quão irritado o cliente está?",
      "criteria": [
        "calmo",
        "um pouco incomodado",
        "irritado",
        "furioso"
      ]
    },
    "quer_cancelar": {
      "type": "noul",
      "instructions": "O cliente ameaça cancelar o serviço"
    },
    "elogio": {
      "type": "noul",
      "instructions": "O cliente está elogiando o atendimento"
    }
  }
}

Em treinamento. Quer usar no seu projeto ou ajudar a definir as perguntas? Fale com a Logo17.

GET /v1/models

Produtos disponíveis e regras de cobrança (billing: tokens por crédito, planos e excedente). Não exige chave.

GET /v1/balance

Saldo em reais disponível para a chave (incluindo o concedido ao projeto dela) e a situação do plano: créditos usados e restantes no ciclo e quando ele termina.

Boas práticas

  • →Use a probabilidade como limite: decida sozinho acima de um valor (ex. 0,9) e mande o resto para revisão.
  • →Escreva perguntas noul afirmativas ("O cliente quer cancelar"), sem dupla negação.
  • →O modelo não faz contas, não conta itens nem compara datas: deixe isso no seu código.
  • →Coloque no state só o que importa para as perguntas: texto irrelevante piora a resposta.