Come usare le API Jev

Le API Jev valutano testo mediante domande definite dalla tua applicazione. Invii state, model e una mappa questions; ricevi decisioni tipizzate in answers, associate agli stessi identificatori. Non è una risposta di chat da cui estrarre successivamente le etichette.

Questa guida riguarda l’integrazione. Per capire casi d’uso, prezzi e limiti del modello, leggi la presentazione di Jev.

Scegli endpoint e chiave corrispondente

Entrambi usano Authorization: Bearer ... e il corpo nativo Jev. Non inviare la chiave di un servizio all’altro. Il gateway non usa /v1/chat/completions; sostituire state con messages cambia il contratto.

Crea una chiave con permessi limitati, verifica il percorso Jev attuale e imposta OMNIAKEY_API_KEY nell’ambiente locale. Non inserire la chiave in codice del browser, Git o schermate condivise. I passaggi generali sono nella guida rapida API (in inglese).

Una richiesta JSON completa

Salva questo contenuto in jev-request.json. La richiesta valuta un messaggio di assistenza per reparto, frustrazione e urgenza. Il testo resta in inglese perché TypeSafe indica che oggi è la lingua più affidabile; valuta l’italiano su campioni rappresentativi del tuo utilizzo.

{
  "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?"
    }
  }
}

Gli ID collegano domande e risposte. Secondo TypeSafe non partecipano all’inferenza: la domanda va in instructions, non soltanto nel nome della chiave. state può anche essere un oggetto o array JSON con testo, per esempio un ticket con campi distinti.

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

Per TypeSafe diretto, usa https://api.typesafe.ai/v1/systemone con $TYPESAFE_API_KEY. Mantieni lo schema JSON e controlla i nomi dei modelli accettati dall’account.

Leggere Choice, Score e Noul

La risposta contiene anche model e usage.input_tokens / usage.output_tokens. Oggi jev-latest punta a jev-1.13.0, ma l’alias può cambiare. Registra la versione che ha effettivamente risposto.

Su una scala di tre livelli, 1.05 si trova poco sopra il livello 1: non è un voto su 100. Leggi legend. Un Noul di 0.8 non autorizza da solo un rimborso. Scegli le soglie usando esempi etichettati. confidence deriva dalla distribuzione e non garantisce la correttezza della decisione.

La risposta completa seguente è un esempio illustrativo, non il risultato di una chiamata reale all’API. I valori e il numero di token servono a spiegare la struttura; i risultati effettivi possono variare.

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

Esempi Python e Node.js

Questi esempi leggono jev-request.json e inviano una sola richiesta. Stampano le risposte native senza presumere un campo OpenAI choices. In produzione aggiungi la politica di tentativi limitati descritta sotto.

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

Usa Python 3 o Node.js con fetch e AbortSignal.timeout integrati. Sono esempi HTTP, non una promessa di supporto nativo nello SDK OpenAI. TypeSafe documenta i propri SDK nella referenza ufficiale.

Contesto, limiti di frequenza e fatturazione

Devono valere due condizioni insieme: 64K token per l’intera richiesta e 32K per state più la singola domanda più lunga. Elimina contesto irrilevante e raggruppa solo le domande che richiedono lo stesso stato.

TypeSafe pubblica 250,000 token al secondo e 1,200 richieste al minuto, con limiti modificabili durante l’accesso iniziale. Sono quote dell’account, non velocità per richiesta né garanzie per OmniaKey. Il gateway può applicare ulteriori restrizioni.

Il prezzo diretto verificato è $0.042 per milione di token di input, con output gratuito. Il consumo di output continua a comparire nella risposta. Questo non rende gratuita tutta l’API e non definisce l’unità di fatturazione del gateway. Verifica la quotazione e i tuoi registri; la guida al modello chiarisce il contesto dei prezzi.

Nel catalogo attuale di OmniaKey, Jev prevede la fatturazione per richiesta. Prima di stimare i costi del gateway, verifica il prezzo aggiornato del modello e i dati di utilizzo nella dashboard.

Errori e nuovi tentativi

Queste definizioni appartengono al servizio diretto. Un gateway può avere errori propri di autenticazione, validazione o fornitore. Controlla anche percorso e model ID esatto. Non condividere chiavi o corpi privati nei dati diagnostici.

Separa la decisione dalle azioni successive: ripetere una classificazione non deve inviare due e-mail o eseguire due rimborsi. Dopo ripetuti fallimenti, restituisci un errore visibile o chiedi una revisione; non trasformarlo silenziosamente in una decisione certa.

Domande frequenti

È la documentazione ufficiale di Jev?

È una guida di integrazione OmniaKey. La referenza TypeSafe definisce lo schema diretto, e la pagina dei modelli prezzi e limiti. La tabella iniziale distingue le due rotte.

Posso inviare immagini o generare testo?

Jev 1.13 accetta testo e restituisce decisioni tipizzate. Prima converti i materiali non testuali in testo o campi. Generare spiegazioni, immagini o video richiede un altro modello o passaggio dell’applicazione.

Alias o versione fissa?

L’alias è comodo per esplorare. In un flusso basato su soglie, valuta una versione supportata, registra model e rivalida le soglie prima del cambio. La disponibilità può differire tra API diretta e gateway.

Fonti

• Referenza API TypeSafe
• Modelli, prezzi, alias e limiti
• Interpretare la confidenza
• Limiti di Jev 1.13