# Como usar a API Jev

> Integre Jev com curl, Python e Node.js. Entenda Choice, Score e Noul, escolha a chave correta e trate contexto, limites, erros e novas tentativas.

- Canonical HTML: https://omniakey.com/pt-BR/blog/jev-api-guide
- Markdown: https://omniakey.com/pt-BR/blog/jev-api-guide.md
- Published: 2026-09-28 (updated 2026-10-24)
- Author: Kiki, COO at OmniaKey
- Language: pt-BR
- Category: API setup
- Reading time: 11 min
- All posts: https://omniakey.com/blog/llms.txt

---

A **API Jev** avalia texto com perguntas definidas pela sua aplicação. Você envia `state`, `model` e um mapa `questions`; as decisões tipadas voltam em `answers`, com os mesmos identificadores. Não é uma API de chat que exige extrair categorias de uma resposta em texto livre.

Este guia trata da integração. Para conhecer os usos, preços e limitações, veja a [explicação do modelo Jev](https://omniakey.com/pt-BR/blog/jev-model-explained).

> **Verificado em 24 de outubro de 2026.** O contrato vem da documentação TypeSafe; a rota do gateway foi conferida na implementação da OmniaKey. Os exemplos passaram por verificações offline, sem um novo teste pago de desempenho. Preços e limites da API direta não valem automaticamente para o gateway.

## Escolha o endpoint e a chave correta

|Serviço|Endpoint POST|Credencial|
|-|-|-|
|OmniaKey|`https://api.omniakey.com/v1/alpha/search`|Chave OmniaKey com acesso a `jev-latest`|
|TypeSafe direto|`https://api.typesafe.ai/v1/systemone`|Chave TypeSafe|

As duas rotas usam `Authorization: Bearer ...` e o corpo nativo do Jev. **Não envie a chave de um serviço ao outro.** O endpoint do gateway não é `/v1/chat/completions`; trocar `state` por `messages` altera o contrato.

Crie uma chave com permissões restritas, confirme a [rota atual do Jev](https://omniakey.com/pt-BR/jev-latest) e defina `OMNIAKEY_API_KEY` no ambiente local. Não coloque a chave no navegador, no Git ou em capturas de tela. O [guia de início da API (em inglês)](https://docs.omniakey.com/en/quick-start) explica a configuração geral.

## Monte uma requisição JSON completa

Salve o exemplo como `jev-request.json`. Ele avalia uma mensagem de suporte para decidir o departamento, o nível de frustração e a urgência. Mantivemos a entrada em inglês porque a TypeSafe informa que esse idioma tem o melhor desempenho atualmente; valide o português com exemplos do seu uso real.

```json
{
  "model": "jev-latest",
  "state": "My payouts have failed for three days. Please help me resolve this today.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this message?",
      "criteria": {
        "billing": "Payments, invoices, or refunds",
        "technical": "Bugs, outages, or integrations",
        "sales": "Pricing, upgrades, or new accounts"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "Does the message express a time-sensitive need?"
    }
  }
}
```

Os IDs conectam perguntas e respostas. Segundo a TypeSafe, o nome da chave não participa da inferência: escreva a tarefa em `instructions`, não apenas no identificador. `state` também pode ser um objeto ou array JSON com texto, como um chamado dividido em campos.

```bash
curl --fail-with-body https://api.omniakey.com/v1/alpha/search \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @jev-request.json
```

No acesso direto à TypeSafe, use `https://api.typesafe.ai/v1/systemone` e `$TYPESAFE_API_KEY`. Mantenha o formato JSON e confira os modelos aceitos pela conta.

## Entenda Choice, Score e Noul

|Tipo|O que definir|Campos retornados|Interpretação|
|-|-|-|-|
|`choice`|Opções e descrições, até 255 opções|`choice`, `probabilities`, `confidence`|Categoria escolhida e distribuição entre as opções|
|`score`|Escala ordenada com 2–10 níveis|`score`, `legend`, `probabilities`, `confidence`|Nível ponderado pelas probabilidades; pode ser fracionário|
|`noul`|Pergunta sim/não, com critérios `true` / `false` opcionais|`noul`|Probabilidade de sim de 0 a 1, não um booleano|

A resposta inclui `model` e `usage.input_tokens` / `usage.output_tokens`. Hoje, `jev-latest` aponta para `jev-1.14.0`, mas aliases podem mudar. Registre a versão que realmente respondeu e, se precisar fixá-la, use `jev-1.14.0`.

Numa escala de três níveis, `1.05` fica um pouco acima do nível 1; não é uma nota de 1,05 em 100. Use `legend`. Um Noul de `0.8` também não autoriza sozinho um reembolso. Defina limiares com exemplos rotulados; `confidence` é derivado da distribuição e não garante uma decisão correta.

A resposta completa abaixo é um exemplo ilustrativo, não o resultado de uma chamada real à API. Os valores e as contagens de tokens explicam a estrutura; os resultados reais podem variar.

```json
{
  "model": "jev-1.14.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.88,
        "technical": 0.12,
        "sales": 0.0
      },
      "confidence": 0.81
    },
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": {
        "0": "Calm",
        "1": "Frustrated",
        "2": "Very angry"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.95,
        "2": 0.05
      },
      "confidence": 0.92
    },
    "is_urgent": {
      "type": "noul",
      "noul": 0.8
    }
  },
  "usage": {
    "input_tokens": 320,
    "output_tokens": 72
  }
}
```

## Exemplos em Python e Node.js

Os exemplos leem `jev-request.json` e fazem uma chamada. Eles imprimem respostas nativas, sem presumir um campo OpenAI `choices`. Em produção, acrescente a política limitada de novas tentativas descrita abaixo.

```python
import json
import os
import urllib.error
import urllib.request
from pathlib import Path

request = urllib.request.Request(
    "https://api.omniakey.com/v1/alpha/search",
    data=Path("jev-request.json").read_bytes(),
    headers={
        "Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise SystemExit(f"Jev request failed: HTTP {error.code}") from None

print(result["model"])
print(json.dumps(result["answers"], indent=2))
```

```javascript
import { readFile } from 'node:fs/promises';

const key = process.env.OMNIAKEY_API_KEY;
if (!key) throw new Error('Set OMNIAKEY_API_KEY first');

const response = await fetch('https://api.omniakey.com/v1/alpha/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${key}`,
    'Content-Type': 'application/json',
  },
  body: await readFile('jev-request.json', 'utf8'),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`Jev request failed: HTTP ${response.status}`);

const result = await response.json();
console.log(result.model);
console.log(result.answers);
```

Use Python 3 ou Node.js com `fetch` e `AbortSignal.timeout` integrados. São exemplos HTTP, não uma promessa de suporte nativo no SDK OpenAI. Os SDKs da própria TypeSafe estão na [documentação oficial](https://docs.typesafe.ai/api).

## Contexto, limites de uso e preço

Na API Jev, as duas condições precisam ser atendidas: **64K tokens para a requisição inteira** e **32K para `state` mais a pergunta individual mais longa**. Remova conteúdo irrelevante e agrupe somente perguntas que precisam do mesmo estado.

A TypeSafe publica **250,000 tokens por segundo e 1,200 requisições por minuto**, sujeitos a ajustes durante o acesso inicial. São limites da conta, não velocidade por requisição nem garantia para a OmniaKey. O gateway pode aplicar restrições adicionais.

O preço direto verificado é **$0.042 por milhão de tokens de entrada**, com saída gratuita. A resposta continua informando a saída consumida. Isso não torna toda a API gratuita nem define a unidade de cobrança do gateway. Consulte a cotação atual e seus registros; a [visão geral do Jev](https://omniakey.com/pt-BR/blog/jev-model-explained) explica o contexto dos valores.

No catálogo atual da OmniaKey, o Jev tem **cobrança por requisição**. Confira o preço vigente do modelo e os registros do painel antes de estimar os custos do gateway.

## Erros e novas tentativas

|Status direto da TypeSafe|Primeiro diagnóstico|Ação|
|-|-|-|
|`401`|A chave pertence ao serviço e o Bearer está correto?|Corrija a credencial, sem repetir a mesma chave inválida|
|`422`|Campos obrigatórios, tipo e `criteria`|Corrija o campo indicado pela mensagem|
|`429`|Limite de requisições ou tokens|Respeite `Retry-After` se houver; use espera exponencial limitada com variação aleatória|
|`529`|Sobrecarga temporária|Tente novamente com limite de tentativas e tempo total|

Esses significados pertencem à API direta. Gateways podem retornar seus próprios erros de autenticação, validação ou provedor. Confira também o caminho e o model ID exato. Não compartilhe chaves nem corpos privados em diagnósticos.

Separe a avaliação dos efeitos no negócio: repetir uma classificação não pode enviar dois e-mails ou emitir dois reembolsos. Se as tentativas falharem, mostre o erro ou encaminhe para revisão; não transforme a falha silenciosamente numa decisão aparentemente certa.

## Perguntas frequentes

### Esta é a documentação oficial do Jev?

É um guia de integração da OmniaKey. A [referência TypeSafe](https://docs.typesafe.ai/api) define o esquema direto, e a [página de modelos](https://docs.typesafe.ai/models), os preços e limites. A tabela inicial diferencia os serviços.

### Posso enviar imagens ou pedir um texto?

O Jev 1.14 aceita texto por padrão e devolve decisões tipadas. Converta materiais não textuais em texto ou campos antes do envio; a entrada de imagens do 1.14 fica atrás de um ajuste experimental. Gerar explicações, imagens ou vídeos exige outro modelo ou etapa.

### Devo usar um alias ou uma versão fixa?

Aliases facilitam a exploração. Para um fluxo com limiares, avalie uma versão suportada, registre `model` e valide novamente antes de mudar. A disponibilidade de modelos pode variar entre gateway e API direta.

## Fontes

- [Referência da API TypeSafe](https://docs.typesafe.ai/api)
- [Modelos, preços, aliases e limites](https://docs.typesafe.ai/models)
- [Como interpretar confiança](https://docs.typesafe.ai/confidence)
- [Limitações do Jev 1.13](https://docs.typesafe.ai/model-jaggedness/jev-1.13)