# Come usare le API Jev > Integra Jev con curl, Python e Node.js. Scopri come leggere Choice, Score e Noul e gestire chiavi API, richieste JSON, limiti di contesto, errori e tentativi. - Canonical HTML: https://omniakey.com/it/blog/jev-api-guide - Markdown: https://omniakey.com/it/blog/jev-api-guide.md - Published: 2026-09-28 (updated 2026-10-24) - Author: Kiki, COO at OmniaKey - Language: it - Category: API setup - Reading time: 11 min - All posts: https://omniakey.com/blog/llms.txt --- 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](https://omniakey.com/it/blog/jev-model-explained). > **Verificato il 24 ottobre 2026.** Il contratto deriva dalla documentazione TypeSafe; il percorso gateway è stato confrontato con l’implementazione OmniaKey. Gli esempi sono stati controllati offline, senza un nuovo test di prestazioni a pagamento. Prezzi e limiti diretti non si applicano automaticamente al gateway. ## Scegli endpoint e chiave corrispondente |Servizio|Endpoint POST|Credenziale| |-|-|-| |OmniaKey|`https://api.omniakey.com/v1/alpha/search`|Chiave OmniaKey abilitata a `jev-latest`| |TypeSafe diretto|`https://api.typesafe.ai/v1/systemone`|Chiave TypeSafe| 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](https://omniakey.com/it/jev-latest) 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)](https://docs.omniakey.com/en/quick-start). ## 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. ```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?" } } } ``` 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. ```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 ``` 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 |Tipo|Cosa definire|Campi restituiti|Interpretazione| |-|-|-|-| |`choice`|Opzioni e descrizioni, fino a 255 opzioni|`choice`, `probabilities`, `confidence`|Etichetta scelta e distribuzione sulle opzioni| |`score`|Rubrica ordinata con 2–10 livelli|`score`, `legend`, `probabilities`, `confidence`|Livello ponderato per probabilità, anche frazionario| |`noul`|Domanda sì/no, criteri `true` / `false` facoltativi|`noul`|Probabilità del sì tra 0 e 1, non un booleano| La risposta contiene anche `model` e `usage.input_tokens` / `usage.output_tokens`. Oggi `jev-latest` punta a `jev-1.14.0`, ma l’alias può cambiare. Registra la versione che ha effettivamente risposto e, se deve restare fissa, scrivi `jev-1.14.0`. 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. ```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 } } ``` ## 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. ```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); ``` 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](https://docs.typesafe.ai/api). ## Contesto, limiti di frequenza e fatturazione Nelle API Jev 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](https://omniakey.com/it/blog/jev-model-explained) 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 |Stato TypeSafe diretto|Prima verifica|Azione| |-|-|-| |`401`|Servizio della chiave e intestazione Bearer|Correggi la credenziale, senza ripetere la stessa chiave errata| |`422`|Campi obbligatori, tipo e `criteria`|Correggi il campo indicato dall’errore| |`429`|Limite di richieste o token|Rispetta `Retry-After` se presente; attesa esponenziale limitata con jitter| |`529`|Sovraccarico temporaneo|Riprova con un massimo di tentativi e di tempo totale| 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](https://docs.typesafe.ai/api) definisce lo schema diretto, e la [pagina dei modelli](https://docs.typesafe.ai/models) prezzi e limiti. La tabella iniziale distingue le due rotte. ### Posso inviare immagini o generare testo? Jev 1.14 accetta testo per impostazione predefinita e restituisce decisioni tipizzate. Prima converti i materiali non testuali in testo o campi; l’input di immagini della 1.14 è dietro un’impostazione sperimentale. 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](https://docs.typesafe.ai/api) - [Modelli, prezzi, alias e limiti](https://docs.typesafe.ai/models) - [Interpretare la confidenza](https://docs.typesafe.ai/confidence) - [Limiti di Jev 1.13](https://docs.typesafe.ai/model-jaggedness/jev-1.13)