Руководство API Jev

API Jev оценивает текст по вопросам, заданным приложением. Запрос содержит state, model и словарь questions; типизированные решения возвращаются в answers под теми же идентификаторами. Это не чат, из свободного текста которого затем нужно извлекать метки.

Здесь рассматривается интеграция. Назначение, стоимость и ограничения модели описаны в обзоре Jev.

Выберите адрес и соответствующий API-ключ

В обоих случаях используются Authorization: Bearer ... и собственный формат Jev. Не отправляйте ключ одного сервиса другому. Маршрут шлюза — не /v1/chat/completions; замена state на messages меняет контракт.

Создайте ключ с ограниченными правами, проверьте текущий маршрут Jev и задайте OMNIAKEY_API_KEY в локальном окружении. Не помещайте ключ в браузерный код, Git или снимки экрана. Общие шаги есть в быстром старте API.

Полный пример JSON-запроса

Сохраните следующий текст в jev-request.json. Один запрос определяет отдел поддержки, степень раздражения и срочность сообщения. Вход в примере оставлен на английском: TypeSafe называет его наиболее сильным языком модели. Русскоязычные задачи проверяйте на собственных репрезентативных данных.

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

Идентификаторы связывают вопросы с ответами. По документации TypeSafe их имена не участвуют в выводе модели, поэтому формулируйте задачу в instructions, а не только в названии ключа. state также может быть JSON-объектом или массивом с текстом, например карточкой обращения с отдельными полями.

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

Для прямого TypeSafe используйте https://api.typesafe.ai/v1/systemone и $TYPESAFE_API_KEY. Сохраните формат JSON и проверьте доступные этому аккаунту имена моделей.

Как читать Choice, Score и Noul

Ответ также содержит model и usage.input_tokens / usage.output_tokens. Сейчас jev-latest указывает на jev-1.13.0, но псевдоним может измениться. При оценке качества сохраняйте фактическую версию ответа.

В шкале из трёх уровней 1.05 означает значение чуть выше уровня 1, а не 1,05 балла из 100. Сверяйтесь с legend. Noul 0.8 сам по себе не разрешает возврат денег. Настраивайте пороги на размеченных примерах. confidence выводится из распределения и не гарантирует правильность решения.

Ниже приведён полный пример ответа для пояснения структуры, а не результат реального вызова API. Значения и количество токенов условные; фактический ответ может отличаться.

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

Вызов из Python и Node.js

Примеры читают jev-request.json и выполняют один запрос. Они выводят исходные ответы, не ожидая поля OpenAI choices. Для эксплуатации добавьте ограниченную политику повторов, описанную ниже.

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

Нужны Python 3 или Node.js со встроенными fetch и AbortSignal.timeout. Это HTTP-примеры, а не утверждение о поддержке схемы Jev в OpenAI SDK. Собственные SDK TypeSafe описаны в официальном справочнике.

Контекст, лимиты запросов и стоимость

Одновременно действуют два ограничения: 64K токенов на весь запрос и 32K на state вместе с самым длинным отдельным вопросом. Удаляйте лишний контекст и объединяйте только вопросы, которым действительно нужно одно состояние.

TypeSafe указывает 250,000 токенов в секунду и 1,200 запросов в минуту, предупреждая об изменениях в период раннего доступа. Это лимиты аккаунта, не скорость одного ответа и не гарантия для OmniaKey. Шлюз может применять дополнительные ограничения.

Проверенная прямая цена — $0.042 за миллион входных токенов, выходные токены бесплатны. Их количество всё равно возвращается. Это не делает весь API бесплатным и не определяет единицу тарификации шлюза. Проверяйте актуальную цену и записи использования; контекст приведён в объяснении модели Jev.

В текущем каталоге OmniaKey Jev оплачивается за каждый запрос. Для расчёта расходов проверьте актуальную цену модели и записи об использовании в панели управления.

Ошибки и повторные попытки

Эти значения описаны для прямого API. У шлюза могут быть свои форматы ошибок авторизации, проверки запроса или провайдера. Если маршрут недоступен, проверьте путь и точный model ID. Не включайте ключи и приватное тело запроса в публикуемую диагностику.

Отделяйте оценку от последующих действий: повтор классификации не должен дважды отправлять письмо или возвращать деньги. После серии неудач показывайте ошибку либо отправляйте случай на проверку, а не незаметно подставляйте уверенное решение по умолчанию.

Частые вопросы

Это официальная документация API Jev?

Это руководство по интеграции OmniaKey. Прямой контракт определён в API-справочнике TypeSafe, цены и лимиты — на странице моделей. Таблица выше разделяет сервисы.

Можно отправлять изображения или генерировать текст?

Jev 1.13 принимает текст и возвращает типизированные решения. Нетекстовые материалы сначала преобразуйте в текст или поля. Для объяснений, изображений или видео нужен другой генеративный шаг.

Что выбрать: псевдоним или фиксированную версию?

Псевдоним удобен для знакомства. В рабочем процессе с порогами оцените поддерживаемую фиксированную версию, сохраняйте model и перепроверяйте пороги перед сменой. Доступные имена у шлюза и прямого API могут различаться.

Источники

• Справочник API TypeSafe
• Модели, цены, псевдонимы и лимиты
• Интерпретация уверенности
• Ограничения Jev 1.13