Jev API guide

The Jev API evaluates text against questions you define and returns typed decisions. Send state, model and a questions map. Read answers under the same question IDs. There is no chat transcript to reconstruct and no free-form answer to parse.

This guide is for a first integration. For what the model does well, its limitations and pricing background, start with Jev model explained.

Choose the endpoint and its matching API key

Both examples use Authorization: Bearer ... and the native Jev body. Do not send an OmniaKey key to TypeSafe, or a TypeSafe key to OmniaKey. The gateway endpoint is not /v1/chat/completions; replacing state with messages changes the contract.

Create a scoped key, check the current Jev model route, and set OMNIAKEY_API_KEY in your local environment. Keep keys out of browser code, source control and screenshots. General key setup is in the API quick start.

Build a complete Jev JSON request

Save this as jev-request.json. It evaluates one support message for routing, frustration and urgency. The example uses English text; TypeSafe says English is currently strongest, so validate other languages on representative inputs.

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

The IDs department, frustration and is_urgent join questions to answers. TypeSafe says those IDs are not used in inference: put the actual task in instructions, not only in the key name. A state can also be a JSON object or array containing text, such as a support record with named fields.

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

For direct TypeSafe access, use https://api.typesafe.ai/v1/systemone with $TYPESAFE_API_KEY instead. Keep the JSON shape; verify the model names your account accepts.

Understand Choice, Score and Noul responses

The response also contains model and usage.input_tokens / usage.output_tokens. Record the resolved model ID when evaluating behavior: jev-latest currently points to jev-1.13.0, and an alias can move later.

For a three-level rubric, a score of 1.05 would fall just above level 1; it would not mean 1.05 out of 100. Use the returned legend. A Noul value of 0.8 is a probability, not permission to execute an irreversible action. Choose thresholds using labeled examples from your application. confidence is derived from the distribution and is not a guarantee that a decision is correct.

The following complete response is an illustrative fixture, not an observed API result. Answer values and token counts are examples; actual results vary.

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

Call the Jev API from Python or Node.js

These examples reuse jev-request.json and make one request. They print the typed answers rather than assuming an OpenAI choices response. Add the bounded retry policy below in a production client.

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 or a Node.js version with built-in fetch and AbortSignal.timeout. These are plain HTTP examples, not a claim that an OpenAI SDK supports Jev's native schema. TypeSafe also publishes its own SDKs in the official documentation.

Context limits, rate limits and billing

The current official model has 64K tokens for the entire request, and a separate 32K limit for state plus the longest single question. Both conditions must hold. Shorten irrelevant input and combine only questions that genuinely need the same state.

TypeSafe lists 250,000 tokens per second and 1,200 requests per minute, with a warning that early-access limits can change. They are account throughput limits, not single-request speed measurements or a promise for your OmniaKey account. A gateway can impose additional limits.

Direct TypeSafe pricing is $0.042 per million input tokens, with output tokens free at the check date. Output usage is still returned. That does not mean all API use is free, nor that the gateway uses the same billing unit or price. Use the current model quote and your usage records for OmniaKey costs; see the pricing and limits explanation.

OmniaKey’s current Jev catalog uses per-request billing. Check the current model quote and dashboard usage records before estimating gateway costs.

Handle authentication, validation and retries

Those status meanings are documented for the direct API. A gateway can return its own authentication, validation or upstream error format. Also check the endpoint path and exact model ID when a route is unavailable. Keep keys and private request bodies out of diagnostics you share.

Separate the model request from downstream side effects: retrying a classification must not send a customer email or issue a refund twice. After repeated failures, return a visible failure or route for review. Do not silently turn a failed decision into a confident default.

Frequently asked questions

Is this the official Jev API documentation?

This is an OmniaKey integration guide. TypeSafe's API reference owns the direct schema and its model page owns direct prices and limits. The endpoint table above distinguishes the routes.

Can I send images or ask Jev to write text?

Jev 1.13 is text-only and returns the typed decisions described above. Extract text from non-text assets first. Generating an explanation, image or video requires another model or application step.

Should I use an alias or a versioned model ID?

An alias is convenient for exploration. For a deployed threshold-based workflow, evaluate a supported versioned ID and record the returned model; revalidate thresholds before changing versions. Gateway model availability can differ from the direct API.

Sources

• TypeSafe API reference
• Models, prices, aliases and limits
• Confidence
• Jev 1.13 limitations