Primeira chamada ao Jev em cinco minutos

Dá para ter a primeira decisão tipada do Jev na mão em poucos minutos, sem instalar biblioteca nenhuma. Este é o caminho na ordem em que ele funciona, com o que a documentação oficial recomenda em cada passo.

Se você ainda não sabe o que o modelo faz, o pilar o que é Jev explica o contrato antes de você escrever código. Se quiser ver a resposta real antes de pegar chave, o nosso playground roda seis perguntas em português contra a API oficial.

Passo 1: o playground oficial

O caminho mais rápido é o playground do console, em console.typesafe.ai/playground. Você cola um texto como state, adiciona uma pergunta e vê a resposta com as probabilidades na hora.

O exemplo que a própria documentação usa para começar é um Noul:

{
  "urgencia": {
    "type": "noul",
    "instructions": "A mensagem transmite urgência?"
  }
}

Depois acrescente mais perguntas e misture os tipos na mesma chamada. Ver as três primitivas respondendo juntas, sobre o mesmo texto, é o que faz a ficha cair — cada pergunta é avaliada de forma independente, e o conjunto vem numa resposta só.

Passo 2: a chave

A chave fica no console, em console.typesafe.ai/settings/keys. Ela autentica a requisição no cabeçalho Authorization, com o esquema Bearer.

Trate a chave como segredo de produção desde o primeiro dia: variável de ambiente ou cofre, nunca no repositório, nunca no navegador. Se o seu site precisa chamar o Jev a partir do front-end, o padrão é uma rota no seu próprio servidor que guarda a chave e repassa apenas o resultado — é exactamente o que fazemos no playground deste site.

Passo 3: a requisição

Três campos no corpo: state (o conteúdo a avaliar), model (quem responde) e questions (o mapa de perguntas).

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Fiz a atualização ontem e agora o sistema não abre. Preciso de solução hoje, a equipe está parada.",
    "model": "jev-latest",
    "questions": {
      "area": {
        "type": "choice",
        "instructions": "Qual time deve atender esta mensagem?",
        "criteria": {
          "cobranca": "Pagamentos, faturas, reembolso",
          "tecnico": "Erros, falhas e problemas de integração",
          "comercial": "Preço, contrato e conta"
        }
      },
      "frustracao": {
        "type": "score",
        "instructions": "Qual o nível de frustração de quem escreveu?",
        "criteria": [
          "Calmo, apenas relatando fatos",
          "Frustrado, mas educado",
          "Muito irritado, linguagem forte"
        ]
      },
      "urgente": {
        "type": "noul",
        "instructions": "A mensagem transmite urgência ou prazo curto?"
      }
    }
  }'

Repare no desenho: uma chamada, três perguntas, três tipos diferentes. É o recomendado. O state entra uma vez e cada pergunta é avaliada em paralelo contra ele, então a pergunta adicional custa apenas os tokens dela.

Passo 4: ler a resposta

A resposta traz uma entrada em answers por pergunta, sob o identificador que você escolheu, e o consumo em usage. Este é o exemplo que a documentação publica no guia de início rápido, com os valores dela:

{
  "model": "jev-latest",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.84, "technical": 0.159, "sales": 0.001 },
      "confidence": 0.596
    },
    "frustration": {
      "type": "score",
      "score": 1.035,
      "legend": { "0": "Calm, just stating facts", "1": "Frustrated but civil", "2": "Very angry, strong language" },
      "confidence": 0.842
    },
    "is_urgent": { "type": "noul", "noul": 0.999 }
  },
  "usage": { "input_tokens": 312, "output_tokens": 48 }
}

Três coisas para notar nesse exemplo oficial. A escolha saiu billing com 0,84 de probabilidade, mas a confiança ficou em 0,596 — a distribuição não estava tão concentrada, porque technical levou 0,159. O Score devolveu 1,035, uma posição entre níveis, com a legenda repetindo o que cada nível significa. E o Noul devolveu 0,999, sem confiança, porque Noul não tem esse campo.

Ler esses três números junto é a diferença entre usar o Jev e só chamar o Jev. A página confiança mostra como transformar isso em regra de código.

Passo 5: erros

Quatro códigos aparecem no primeiro dia, e a documentação diz o que significam:

Os limites de taxa publicados hoje são de 250 mil tokens por segundo e 1.200 requisições por minuto, e a própria empresa avisa que eles podem mudar sem aviso durante o acesso antecipado. Os SDKs oficiais já repetem com backoff e respeitam o cabeçalho retry-after.

Passo 6: sair do curl

Quando a primeira chamada funcionar, troque o curl por um SDK oficial. Em Python, a instalação é pip install typesafe-sdk (ou uv add typesafe-sdk), o cliente lê a chave de TYPESAFE_API_KEY e o modelo padrão é jev-latest. O caminho completo, com retentativa e tratamento de exceção, está em SDK Python do Jev.

Se você usa um agente de código, a TypeSafe publica uma skill oficial que ensina ao agente as formas de requisição e resposta — instalar antes evita o vício de uma pergunta por chamada, que é o erro mais comum de quem começa.

O índice desta seção, com o que vem depois, está em como usar o Jev. Para desenhar boas perguntas, vá para primitivas.