API

Jev — modello decisionale

Il modello decisionale Jev di TypeSafe risponde a domande tipizzate su testo o JSON: scelta di un’opzione, valutazione su una scala oppure «sì/no» con probabilità. Non è una chat e non genera testo.

Guida completa

POSThttps://api.ailoot.ai/v1/systemone

curl https://api.ailoot.ai/v1/systemone \
  -H "Authorization: Bearer $AILOOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Aiuto! I miei pagamenti in uscita non vanno a buon fine da 3 giorni.",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Questo esprime urgenza?"
      }
    }
  }'

import json, os, urllib.request

body = {
    "model": "jev-latest",
    "state": "Aiuto! I miei pagamenti in uscita non vanno a buon fine da 3 giorni.",
    "questions": {
        "is_urgent": {"type": "noul", "instructions": "Questo esprime urgenza?"},
    },
}
req = urllib.request.Request(
    "https://api.ailoot.ai/v1/systemone",
    data=json.dumps(body).encode(),
    headers={"Authorization": "Bearer " + os.environ["AILOOT_API_KEY"],
             "Content-Type": "application/json"},
)
with urllib.request.urlopen(req, timeout=60) as resp:
    result = json.load(resp)
print(result["answers"]["is_urgent"]["noul"])  # 0.95

const resp = await fetch("https://api.ailoot.ai/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AILOOT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "jev-latest",
    state: "Aiuto! I miei pagamenti in uscita non vanno a buon fine da 3 giorni.",
    questions: {
      is_urgent: { type: "noul", instructions: "Questo esprime urgenza?" },
    },
  }),
});
const result = await resp.json();
if (!resp.ok) throw new Error(`${resp.status} ${JSON.stringify(result)}`);
console.log(result.answers.is_urgent.noul); // 0.95

200 OK

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

Jev è un modello decisionale di classe System One di TypeSafe. Non scrive testo e non conversa: gli passi uno stato (state) — testo o JSON — e un insieme di domande, e ricevi valori tipizzati con probabilità. Il codice può subito gestire diramazioni, ordinamenti e instradamenti in base a questi valori, senza analizzare testo libero.

Tutte le domande di una richiesta vengono valutate in parallelo e indipendentemente, rispetto allo stesso state. Secondo TypeSafe, aggiungere domande cambia poco il tempo di risposta e le domande non interferiscono tra loro.

Voce	In breve
Modello	`jev-latest` — alias dell’ultima versione stabile di Jev; scheda nel catalogo
Metodo	`POST /v1/systemone`. Non è una chat: i formati OpenAI, Anthropic e Gemini non sono adatti a Jev. La risposta arriva intera, come un unico JSON
Input accettato	Solo testo: stringa, oggetto JSON o array di testi. Converti prima immagini, audio e video in testo
Contesto	64K token per richiesta — state e tutte le domande insieme; state insieme alla domanda più lunga — fino a 32K
Lingua	Secondo TypeSafe, il modello è più preciso in inglese; accetta altre lingue, ma con precisione inferiore — verifica sui tuoi dati
Prezzo	Input $0.084 per 1 milione di token, output gratuito

Richiesta

Autorizzazione

Authorizationheaderobbligatorio
Chiave Ailoot nel formato Bearer sk-….

Corpo della richiesta

modelstringobbligatorio
jev-latest.
statestring | object | arrayobbligatorio
Contenuto da valutare: stringa di testo o JSON — richiesta di un cliente, record del database, conversazione, stato corrente della tua applicazione. Un oggetto con nomi dei campi chiari è in genere più comodo di una sola stringa.
questionsobjectobbligatorio
Domande. Scegli tu le chiavi e le risposte arriveranno con le stesse chiavi; la chiave non influisce sulla risposta — la domanda si specifica in instructions.
questions.*.typestringobbligatorio
noul, choice oppure score — vedi sotto.
questions.*.instructionsstring | object | arrayobbligatorio
La domanda stessa. Una domanda lunga con dati può essere passata come oggetto: domanda in un campo, dati negli altri; fai riferimento ai campi per nome tra backtick.
questions.*.criteriaobject | array
Opzioni di risposta specifiche per tipo: descrizioni di «sì» e «no» per noul (facoltative), dizionario delle opzioni per choice, elenco ordinato dei livelli per score.

Tipi di domande

Tipo	Cosa chiede	Cosa restituisce
`noul`	Se un’affermazione è vera: sì o no	`noul` — probabilità di «sì» da 0 a 1
`choice`	Quale delle opzioni date è adatta	`choice`, `probabilities`, `confidence`
`score`	Dove si colloca state nella tua scala di livelli	`score`, `legend`, `probabilities`, `confidence`

I tipi possono essere combinati nella stessa richiesta.

noul — sì o no

Il campo criteria è facoltativo: può descrivere il significato di «sì» (true) e «no» (false). La risposta noul — un numero da 0 (no) a 1 (sì).

"is_urgent": {
  "type": "noul",
  "instructions": "Questo esprime urgenza?",
  "criteria": {
    "true": "Con esplicita urgenza temporale",
    "false": "Nessuna urgenza espressa"
  }
}

"is_urgent": {
  "type": "noul",
  "noul": 0.95
}

choice — scelta di un’opzione

criteria — dizionario «opzione → descrizione»; se la descrizione non serve, specifica null. Fino a 255 opzioni. Nella risposta choice — l’opzione più probabile, probabilities — la probabilità di ogni opzione (somma 1), confidence — il grado di confidenza da 0 a 1.

"department": {
  "type": "choice",
  "instructions": "Quale team dovrebbe occuparsene?",
  "criteria": {
    "billing": "Pagamenti, fatturazione, rimborsi",
    "technical": "Bug, interruzioni, integrazioni",
    "sales": "Prezzi, upgrade, nuovi clienti"
  }
}

"department": {
  "type": "choice",
  "choice": "billing",
  "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
  "confidence": 0.81
}

score — valutazione su una scala

criteria — livelli dal più basso al più alto, massimo 10 (TypeSafe ne consiglia almeno due). Nella risposta score — valore ponderato sulle probabilità dei livelli (può trovarsi tra due livelli), legend — numero del livello e relativa descrizione, probabilities e confidence. Secondo TypeSafe, score è adatto al confronto con una soglia, ma non come numero esatto tra i livelli.

"frustration": {
  "type": "score",
  "instructions": "Quanto è frustrato il cliente?",
  "criteria": ["Calmo", "Frustrato", "Molto arrabbiato"]
}

"frustration": {
  "type": "score",
  "score": 1.05,
  "legend": { "0": "Calmo", "1": "Frustrato", "2": "Molto arrabbiato" },
  "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
  "confidence": 0.92
}

Risposta

modelstring
Versione del modello che ha risposto. L’alias jev-latest passa nel tempo a versioni nuove: se hai calibrato le soglie confidence su una versione specifica, controlla questo campo.
answersobject
Una risposta per ogni domanda, con le stesse chiavi. Ogni risposta contiene type, per choice e score anche confidence.
usageobject
input_tokens e output_tokens. Vengono addebitati solo i token di input.

Più domande in una sola richiesta

Invia tutte le domande sullo stesso state in una richiesta: sono valutate in parallelo e state viene trasmesso una sola volta. Secondo TypeSafe, nel loro esempio con 13 domande una richiesta unica costava 12,2 volte meno ed era 10 volte più veloce di 13 richieste separate inviate in sequenza, con le stesse risposte.

Conviene dividere un giudizio complesso in domande semplici e combinare le risposte nel codice: ad esempio, invece di «valuta la proposta», valutazioni separate di mercato, fattibilità e differenze rispetto ai concorrenti. I pesi si modificano così nel codice, non nel testo della domanda.

{
  "model": "jev-latest",
  "state": "Aiuto! I miei pagamenti in uscita non vanno a buon fine da 3 giorni.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Quale team dovrebbe occuparsene?",
      "criteria": {
        "billing": "Pagamenti, fatturazione, rimborsi",
        "technical": "Bug, interruzioni, integrazioni",
        "sales": "Prezzi, upgrade, nuovi clienti"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "Quanto è frustrato il cliente?",
      "criteria": ["Calmo", "Frustrato", "Molto arrabbiato"]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "Questo esprime urgenza?"
    }
  }
}

Quando è adatto

Instradamento. Inviare una richiesta del cliente al reparto giusto e una richiesta al gestore giusto: codice semplice, modello grande o persona.
Ordinamento e priorità. Urgenza, tono e rischio — su una scala con soglie nel codice.
Moderazione e verifiche. Se un messaggio viola le regole, una fonte conferma una citazione o un documento contiene la risposta — prima che il testo prosegua.
Punteggio e ordinamento. Valutare documenti, candidati o frammenti trovati secondo i propri criteri e decidere nel codice cosa prosegue.
Al posto di un fragile «restituisci JSON». Una chiamata che restituisce valori tipizzati per costruzione, anziché testo da analizzare.

Quando non è adatto

Chat, risposte all’utente, generazione di testo o codice. Jev non scrive testo — per questo esistono modelli testuali.
Come modello per Claude Code, Cursor e altri agenti. Non puoi sostituire il modello dell’agente con jev-latest: l’agente ha bisogno di un modello che scriva testo e chiami strumenti. Jev può essere chiamato dal codice che l’agente scrive per te.
Aritmetica, conteggi e confronto di date. Secondo TypeSafe, è più affidabile farlo nel codice e chiedere al modello solo la parte semantica — ad esempio estrarre le parti di una data tramite choice.
Immagini, audio e video. Il modello accetta solo testo — converti questi dati in testo in anticipo.

Prezzo

Vengono addebitati solo i token di input — campo usage.input_tokens della risposta: $0.084 per 1 milione. I token di output sono gratuiti.

La richiesta dell’esempio in questa pagina (296 token di input) costa meno di $0.0001.

Prima della richiesta Ailoot riserva un importo sul saldo e dopo la risposta addebita una sola volta il consumo effettivo — come funziona.

Limiti

Voce	Limite
Richiesta completa: state e tutte le domande	64K token
state insieme alla domanda più lunga	32K token
Opzioni in un singolo choice	fino a 255
Livelli in un singolo score	da 2 a 10
Input	solo testo: stringa, oggetto JSON o array di testi

I limiti del modello sono dichiarati da TypeSafe. I limiti della tua chiave e del saldo valgono come per qualsiasi modello Ailoot: Errori e limiti.

Errori

Gli errori arrivano nel formato comune di Ailoot API: codice, testo chiaro e Request ID. I più frequenti per questo metodo sono:

Codice	Quando	Cosa fare
400 `invalid_request`	Il corpo non ha superato la verifica: manca state, model o questions, type sconosciuto, più di 255 opzioni per choice o più di 10 livelli per score	Correggi la richiesta in base al testo dell’errore: senza modifiche verrà rifiutata di nuovo
400 `context_length_exceeded`	state e le domande superano insieme il limite del modello	Filtra state nel codice, mantenendo ciò che serve alle domande
401 `invalid_api_key`	La chiave manca o non è valida	Trasmetti la chiave nell’header Authorization
402 `insufficient_balance`	Il saldo libero non basta per la riserva	Ricarica il saldo
404 `model_not_found`, `unsupported_endpoint`	ID errato o modello chiamato con il metodo sbagliato, ad esempio tramite /v1/chat/completions	Chiama jev-latest solo tramite POST /v1/systemone
429 `rate_limit_exceeded`	Troppe richieste	Attendi i secondi indicati nell’header Retry-After e riprova
503 `model_overloaded`, `model_unavailable`	Il modello è temporaneamente sovraccarico o non disponibile	Se X-Should-Retry: true — riprova dopo Retry-After secondi; se false — controlla prima il Request ID nella cronologia
504 `model_timeout`	Il modello non ha risposto in tempo	Non inviare di nuovo la richiesta prima di aver controllato il Request ID nella cronologia

L’elenco completo dei codici è nella pagina Errori e limiti.

Hai altre domande? Invia il Request ID e una descrizione — ti aiuteremo a chiarire il problema.Contatta l’assistenza