Como usar a API Jev

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.

Escolha o endpoint e a chave correta

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 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) 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.

{
  "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.

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

A resposta inclui model e usage.input_tokens / usage.output_tokens. Hoje, jev-latest aponta para jev-1.13.0, mas aliases podem mudar. Registre a versão que realmente respondeu.

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.

{
  "model": "jev-1.13.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.

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))

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.

Contexto, limites de uso e preço

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 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

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 define o esquema direto, e a página de modelos, os preços e limites. A tabela inicial diferencia os serviços.

Posso enviar imagens ou pedir um texto?

O Jev 1.13 aceita texto e devolve decisões tipadas. Converta materiais não textuais em texto ou campos antes do envio. 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
• Modelos, preços, aliases e limites
• Como interpretar confiança
• Limitações do Jev 1.13