Как использовать Jev API

Jev предоставляет единственный endpoint. Вы отправляете state и набор questions; он возвращает типизированные ответы с вероятностями. Вот всё, что нужно для первого вызова.

1. Endpoint

Каждый запрос — это POST на https://api.typesafe.ai/v1/systemone, с аутентификацией через токен Bearer. Официальные SDK читают ваш ключ из переменной окружения TYPESAFE_API_KEY.

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Customer: I was charged twice and I am furious.",
    "questions": {
      "topic": {
        "type": "choice",
        "instructions": "What is the issue about?",
        "criteria": { "billing": "money problems", "bug": "broken product" }
      },
      "urgent": {
        "type": "noul",
        "instructions": "Escalate to a human now?"
      }
    }
  }'

curl https://jevtypesafeai.com/api/v1/decide \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route":    { "type": "choice", "instructions": "Where should this go?",
                    "criteria": { "billing": "money", "bug": "broken", "account": "login" } },
      "urgency":  { "type": "score",  "instructions": "How urgent is this?",
                    "criteria": ["routine", "today", "urgent", "critical"] },
      "escalate": { "type": "noul",   "instructions": "Escalate to a human now?" }
    }
  }'

2. Тело запроса

Три поля:

• model — jev-latest, или зафиксируйте версию вроде jev-1.13.0, если вы настраиваете пороги.
• state — контекст в виде строки, объекта JSON или массива текста. До ~64k токенов вместе с вашими вопросами.
• questions — отображение имён вопросов на объекты вопросов. Все они оцениваются за один round trip.

3. Три типа вопросов

choice — выбрать один вариант

Задайте карту критериев из до 255 помеченных вариантов. Jev возвращает ключ-победитель, вероятность по каждому варианту и уверенность.

"topic": {
  "type": "choice",
  "instructions": "What is the primary issue?",
  "criteria": {
    "billing": "billing or payment problem",
    "bug": "the product is broken",
    "account": "login or access"
  }
}

score — позиция на шкале

Задайте упорядоченный массив критериев из 2–10 описаний уровней. Jev возвращает (возможно, дробный) score плюс полное распределение.

"severity": {
  "type": "score",
  "instructions": "How urgent is this?",
  "criteria": [
    "routine",
    "handle today",
    "urgent",
    "critical, about to churn"
  ]
}

noul — откалиброванное да/нет

Без критериев — только инструкции. Jev возвращает noul, вероятность от 0 до 1.

"escalate": {
  "type": "noul",
  "instructions": "Escalate to a human immediately?"
}

4. Ответ

Вы получаете обратно разрешённую модель, карту answers и расход токенов:

{
  "model": "jev-1.13.0",
  "answers": {
    "topic":    { "type": "choice", "choice": "billing",
                  "confidence": 1.0,
                  "probabilities": { "billing": 1.0, "bug": 0.0, "account": 0.0 } },
    "severity": { "type": "score", "score": 3.0, "confidence": 1.0,
                  "legend": { "0": "routine", "3": "critical, about to churn" },
                  "probabilities": { "0": 0.0, "3": 1.0 } },
    "escalate": { "type": "noul", "noul": 0.8 }
  },
  "usage": { "input_tokens": 434, "output_tokens": 75 }
}

Поскольку типы фиксированы, вы можете ветвиться на результатах обычным кодом — if (answers.escalate.noul > 0.7) — без разбора, без regex и без риска некорректного ответа.

5. Лимиты и хорошие практики

• Лимиты частоты: 250,000 tokens/second и 1,200 requests/minute.
• Контекст: до 64k токенов на state + все вопросы; 32k на state + один самый длинный вопрос.
• Фиксируйте версии в продакшене, если важны ваши пороги — jev-latest может менять поведение.
• Группируйте вопросы в один вызов вместо множества; они выполняются параллельно и разделяют стоимость state.
• Используйте уверенность, чтобы автоматически обрабатывать лёгкие случаи и направлять только неопределённые к человеку или более крупной модели.

Хотите увидеть это до написания кода? Каждый пример на этой странице выполняется вживую в playground. За официальными ключами и полной документацией обращайтесь на docs.typesafe.ai.