Como Obter uma Chave API Jev (TypeSafe AI)?

Jev é o modelo de decisão da TypeSafe AI. Você envia a ele um pedaço de estado e um conjunto de perguntas tipadas, e ele responde com probabilidades em vez de prosa. Este guia aborda a chave de API do Jev e sua primeira requisição; para entender o que é Jev e por que ele retorna números em vez de texto, leia o que é Jev primeiro. Para ficar claro, já que os resultados da busca são confusos: este é Jev, o modelo de IA da TypeSafe, não FaZe Jev o YouTuber e não a vacina JEV.

Uma chave de API Jev funciona como qualquer outro token de portador (bearer token), então se você é novo no padrão, o que é uma chave de API cobre o básico. O acesso direto à API está em acesso antecipado, então o primeiro passo é sair da lista de espera. Depois disso, você criará a chave, aprenderá o formato da requisição, chamará o endpoint com curl e o SDK Python, lerá os campos de probabilidade e conectará a requisição ao Apidog com asserções sobre essas probabilidades. Se você não puder esperar, o mesmo modelo está no Vercel AI Gateway sem lista de espera; o FAQ cobre essa rota.

Passo 1: obtenha acesso antecipado e depois crie a chave

O Jev está em acesso antecipado no momento desta redação. A publicação de lançamento da TypeSafe diz que está "trazendo desenvolvedores da lista de espera o mais rápido possível", então junte-se à lista de espera em typesafe.ai e aguarde o convite para o console; ainda não há inscrição de autoatendimento. Uma vez que sua conta do console esteja ativa, vá para console.typesafe.ai/settings/keys e crie uma chave. Copie-a uma vez e trate-a como uma senha.

Exporte-a como uma variável de ambiente em vez de colá-la no código:

export TYPESAFE_API_KEY="ts_..."

Os exemplos oficiais do curl e o SDK Python leem TYPESAFE_API_KEY do ambiente, então uma variável cobre todos os exemplos abaixo. Se uma chave for parar em um commit, rotacione-a no console e execute uma verificação de vazamento de chave de API em todo o repositório.

Passo 2: entenda o formato da requisição

Cada chamada Jev é um único POST https://api.typesafe.ai/v1/systemone com três campos no corpo, documentados na referência da API TypeSafe:

Cada pergunta é um dos três primitivos:

A resposta também carrega model e usage.input_tokens / usage.output_tokens. Perguntas de diferentes tipos podem compartilhar um estado e retornar em uma única viagem de ida e volta.

Passo 3: faça a primeira requisição com curl

Esta requisição executa todos os três primitivos contra um ticket de suporte:

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Meu cartão foi cobrado duas vezes por um único pedido e ninguém respondeu em três dias.",
    "questions": {
      "needs_review": {
        "type": "noul",
        "instructions": "Este ticket precisa de um agente humano?",
        "criteria": {
          "true": "dinheiro, legal, ou uma reclamação não respondida",
          "false": "uma pergunta rotineira que um bot pode fechar"
        }
      },
      "route": {
        "type": "choice",
        "instructions": "Encaminhe este ticket para uma equipe.",
        "criteria": {
          "billing": "problemas de pagamento ou cobrança",
          "shipping": "problemas de entrega",
          "technical": "bugs de aplicação"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "Qual a urgência deste ticket?",
        "criteria": ["baixa", "média", "alta"]
      }
    }
  }'

Uma resposta se parece com isto (os valores são ilustrativos):

{
  "model": "jev-1.13.0",
  "answers": {
    "needs_review": { "type": "noul", "noul": 0.97 },
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.98,
      "probabilities": { "billing": 0.98, "shipping": 0.01, "technical": 0.01 }
    },
    "urgency": {
      "type": "score",
      "score": 1.6,
      "confidence": 0.62,
      "legend": { "0": "low", "1": "medium", "2": "high" },
      "probabilities": { "0": 0.02, "1": 0.36, "2": 0.62 }
    }
  },
  "usage": { "input_tokens": 190, "output_tokens": 0 }
}

Passo 4: leia os campos de probabilidade

Leia os números precisamente:

• noul é a probabilidade de "sim". 0.97 significa que Jev tem 97% de certeza de que este ticket precisa de um humano.
• choice é a opção de maior probabilidade, probabilities lista todas as opções, e confidence diz o quão decisiva foi a escolha. Uma rota de 0.98 é segura para automatizar; uma rota de 0.51 com 0.47 na segunda opção é um cara ou coroa.
• score é a posição ponderada pela probabilidade entre os níveis ordenados, então 1.6 está entre "média" (1) e "alta" (2). legend mapeia cada índice de volta ao seu rótulo, e probabilities mostra a distribuição completa.

Como a saída é uma distribuição, não um rótulo, você define o limite, não o modelo. É por isso que as asserções no Passo 6 testam números.

Passo 5: a mesma chamada com o SDK Python

Instale o SDK; o cliente pega TYPESAFE_API_KEY do ambiente:

pip install typesafe-sdk

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="Meu cartão foi cobrado duas vezes por um único pedido e ninguém respondeu em três dias.",
        questions={
            "needs_review": Noul(
                instructions="Este ticket precisa de um agente humano?",
                criteria={"true": "dinheiro, legal, ou uma reclamação não respondida",
                          "false": "uma pergunta rotineira que um bot pode fechar"},
            ),
            "route": Choice(
                instructions="Encaminhe este ticket para uma equipe.",
                criteria={"billing": "problemas de pagamento ou cobrança",
                          "shipping": "problemas de entrega",
                          "technical": "bugs de aplicação"},
            ),
            "urgency": Score(
                instructions="Qual a urgência deste ticket?",
                criteria=["baixa", "média", "alta"],
            ),
        },
    )

print(response.nouls["needs_review"].noul)
print(response.choices["route"].choice, response.choices["route"].probabilities)
print(response.scores["urgency"].score)

As respostas são agrupadas por tipo no objeto de resposta (nouls, choices, scores). Existe um SDK JavaScript com o mesmo formato, e se você já estiver no Vercel AI Gateway, experimental_evaluate do AI SDK 7 chama o modelo como typesafe-ai/jev, com uma diferença: o tipo de pergunta booleana retorna um campo probability em vez de noul.

Passo 6: armazene e teste a chave de API Jev no Apidog

O Curl prova que a chave funciona uma vez. O Apidog torna a requisição rerunável, asserível e mockável para toda a equipe.

Armazene a chave como uma variável secreta. Crie um ambiente chamado TypeSafe e adicione TYPESAFE_API_KEY como um segredo para que seu valor permaneça mascarado na UI e fora das exportações; ambientes Apidog e variáveis secretas explica a configuração. Defina a autenticação na requisição para Bearer Token com {{TYPESAFE_API_KEY}} como valor.

Crie a requisição POST. Adicione um POST para https://api.typesafe.ai/v1/systemone, cole o corpo JSON do Passo 3 e envie-o. O painel de resposta renderiza a árvore de respostas, para que você possa verificar as probabilidades antes de escrever uma asserção.

Assert sobre probabilidades, não sobre prosa. No construtor visual de asserções, aponte expressões JSONPath para os campos que você deseja:

• $.answers.needs_review.noul é maior que 0.9
• $.answers.route.choice é igual a billing
• $.answers.route.probabilities.billing é maior que 0.8
• $.answers.urgency.score é maior ou igual a 1
• $.usage.input_tokens é menor que 1000

Se você preferir scripts, o pós-processador aceita a API pm familiar:

const body = pm.response.json();
pm.test("ticket sinalizado para um humano", () => {
  pm.expect(body.answers.needs_review.noul).to.be.above(0.9);
});
pm.test("encaminhado para faturamento", () => {
  pm.expect(body.answers.route.choice).to.eql("billing");
});

Salve-o como um cenário de teste. Coloque a requisição em um cenário de teste com um pequeno CSV de tickets e rotas esperadas, e execute-o a cada mudança em suas instruções ou critérios. Edições de prompt são mudanças de código; um cenário de dez linhas detecta a edição que silenciosamente move um 0.95 para um 0.6. O mesmo cenário é executado em CI através do Apidog CLI, então uma regressão bloqueia a fusão.

Simule o formato de resposta declarado. Defina o esquema de resposta no endpoint (os três objetos de resposta mais usage), e o smart mock do Apidog servirá probabilidades falsas realistas imediatamente. O frontend pode construir o badge "precisa de revisão" e a UI de roteamento contra o mock antes que o backend seja lançado, então trocar a URL do mock pelo endpoint real com uma única mudança de ambiente.

Para vagas de planejamento: o plano Gratuito do Apidog inclui 4 usuários, e os níveis pagos são por vaga.

Limites no código

Uma vez que as asserções passem, os mesmos números impulsionam a lógica de produção. Mantenha os limites em um só lugar e nomeie-os:

REVIEW_THRESHOLD = 0.9
AUTO_ROUTE_CONFIDENCE = 0.85

needs_review = response.nouls["needs_review"].noul >= REVIEW_THRESHOLD
route = response.choices["route"]

if route.confidence >= AUTO_ROUTE_CONFIDENCE and not needs_review:
    assign(ticket, team=route.choice)
else:
    queue_for_human(ticket, suggested=route.choice)

Registre o mapa completo de probabilities com cada decisão para que você possa ajustar os limites a partir de dados reais mais tarde, e faça da revisão humana o padrão quando a confiança for baixa; o modelo está dizendo que não tem certeza.

Limites, preços e modelos

Diretamente da página de modelos da TypeSafe:

A esse preço, um milhão de tickets curtos custam menos de $10. A TypeSafe também afirma que o Jev não é treinado em requisições ou respostas de clientes.

Erros comuns e como corrigi-los

Um 422 é o que você mais encontrará ao iterar; o esquema de endpoint do Passo 6 captura a maioria deles antes que a requisição saia da sua máquina.

FAQ

Existe um nível gratuito para a API Jev? A documentação pública lista preços por token e não descreve um nível gratuito ou créditos iniciais, e o acesso em si está em lista de espera por enquanto. Verifique o console assim que seu convite chegar para a oferta atual, e trate qualquer valor que você veja em outro lugar como não oficial.

Posso obter várias respostas de uma requisição? Sim. questions é um mapa, então um noul, uma escolha e um score podem ser executados contra um estado em uma única chamada. É mais barato que três requisições e mantém as respostas consistentes porque compartilham uma única entrada.

Como isso é diferente das saídas estruturadas em um modelo de chat? Saídas estruturadas forçam um modelo de linguagem a emitir JSON válido, mas os valores internos ainda são tokens gerados, e um campo de "confiança" é um texto que o próprio modelo escreveu. Jev retorna probabilidades medidas como a saída nativa, e é por isso que você pode afirmar noul > 0.9 e confiar na comparação.

Preciso do SDK da TypeSafe se estiver no Vercel? Não. O Vercel AI SDK expõe o Jev através de experimental_evaluate com typesafe-ai/jev como ID do modelo. Você se autenticará com sua chave de AI Gateway em vez de uma chave TypeSafe, e a resposta booleana retornará como probability.

Próximos passos

Agora você tem uma chave de API Jev, uma requisição funcionando em curl e Python, e uma leitura clara de noul, choice e score. Coloque a requisição no Apidog, adicione as asserções de probabilidade e salve o cenário de teste para que as edições de prompt sejam testadas como código. Baixe o Apidog para acompanhar.