Panduan API Jev

API Jev menilai teks berdasarkan pertanyaan yang ditentukan aplikasi. Kirim state, model, dan peta questions, lalu baca keputusan bertipe di answers dengan ID pertanyaan yang sama. Ini bukan respons chat berupa teks bebas yang perlu diekstrak lagi menjadi label.

Panduan ini membahas integrasi. Untuk kegunaan, harga, dan keterbatasan model, baca penjelasan model Jev.

Pilih endpoint dan API key yang sesuai

Keduanya memakai Authorization: Bearer ... dan body asli Jev. Jangan kirim key suatu layanan ke layanan lain. Endpoint gateway bukan /v1/chat/completions; mengganti state dengan messages mengubah kontraknya.

Buat key dengan izin terbatas, periksa rute Jev saat ini, lalu atur OMNIAKEY_API_KEY pada environment lokal. Jangan masukkan key ke kode browser, Git, atau tangkapan layar. Langkah umum tersedia di panduan awal API (bahasa Inggris).

Buat permintaan JSON lengkap

Simpan contoh berikut sebagai jev-request.json. Satu pesan bantuan dinilai untuk menentukan departemen, tingkat frustrasi, dan urgensi. Input contoh tetap berbahasa Inggris karena TypeSafe menyebut bahasa itu paling kuat saat ini; uji bahasa Indonesia dengan sampel pekerjaan Anda sendiri.

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

ID menghubungkan pertanyaan dengan jawaban. Menurut TypeSafe, nama ID tidak dipakai dalam inferensi: tulis tugas pada instructions, bukan hanya pada nama key. state juga boleh berupa objek atau array JSON berisi teks, misalnya tiket bantuan dengan beberapa kolom.

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

Untuk akses langsung TypeSafe, ganti URL menjadi https://api.typesafe.ai/v1/systemone dan key menjadi $TYPESAFE_API_KEY. Pertahankan struktur JSON dan pastikan model yang dipilih diterima akun tersebut.

Membaca Choice, Score, dan Noul

Respons juga memuat model serta usage.input_tokens / usage.output_tokens. Saat diperiksa, jev-latest mengarah ke jev-1.13.0. Alias bisa berubah, jadi catat versi yang benar-benar menjawab saat mengevaluasi hasil.

Dalam rubrik tiga tingkat, 1.05 sedikit di atas tingkat 1, bukan nilai 1,05 dari 100. Gunakan legend. Nilai Noul 0.8 juga bukan izin otomatis untuk melakukan pengembalian dana. Tentukan ambang dengan data berlabel. confidence berasal dari distribusi dan tidak menjamin keputusan benar.

Respons lengkap berikut adalah contoh ilustratif, bukan hasil panggilan API yang sebenarnya. Nilai jawaban dan jumlah token hanya untuk menjelaskan strukturnya; hasil nyata dapat berbeda.

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

Contoh Python dan Node.js

Contoh berikut membaca jev-request.json dan mengirim satu permintaan. Kode menampilkan jawaban asli, tidak mengharapkan field OpenAI choices. Tambahkan kebijakan retry terbatas di bagian berikut untuk penggunaan produksi.

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

Gunakan Python 3 atau Node.js yang menyediakan fetch dan AbortSignal.timeout. Ini contoh HTTP, bukan klaim bahwa SDK OpenAI mendukung schema Jev secara langsung. SDK milik TypeSafe dijelaskan dalam referensi resmi.

Batas konteks, rate limit, dan biaya

Dua batas berlaku bersamaan: 64K token untuk seluruh permintaan dan 32K untuk state ditambah pertanyaan tunggal terpanjang. Hapus konteks yang tidak relevan dan gabungkan hanya pertanyaan yang membutuhkan state yang sama.

TypeSafe mencantumkan 250,000 token per detik dan 1,200 permintaan per menit, yang bisa disesuaikan selama akses awal. Ini batas akun, bukan kecepatan satu permintaan atau jaminan untuk OmniaKey. Gateway dapat menerapkan batas tambahan.

Harga langsung yang diperiksa adalah $0.042 per satu juta token input, dengan token output gratis. Jumlah output tetap dilaporkan. Ini tidak membuat seluruh API gratis dan tidak menetapkan unit penagihan gateway. Periksa harga serta catatan penggunaan pada rute Anda; artikel model Jev memberi konteks biaya dan batasnya.

Dalam katalog OmniaKey saat ini, Jev dikenai biaya per permintaan. Periksa harga model terbaru dan catatan penggunaan di dasbor sebelum memperkirakan biaya gateway.

Menangani error dan retry

Arti status ini berasal dari API langsung. Gateway dapat mempunyai format error autentikasi, validasi, atau upstream sendiri. Periksa juga path dan model ID yang tepat. Jangan membagikan key atau body privat dalam diagnostik.

Pisahkan evaluasi dari tindakan lanjutan: mengulang klasifikasi tidak boleh mengirim dua email atau melakukan refund dua kali. Setelah beberapa kegagalan, tampilkan error atau arahkan ke pemeriksaan, bukan diam-diam mengubah kegagalan menjadi keputusan pasti.

Pertanyaan umum

Apakah ini dokumentasi resmi API Jev?

Ini panduan integrasi OmniaKey. Referensi TypeSafe menentukan schema langsung, sedangkan halaman model menentukan harga dan kuotanya. Tabel endpoint membedakan kedua layanan.

Bisakah Jev menerima gambar atau menulis teks?

Jev 1.13 menerima teks dan mengembalikan keputusan bertipe. Ubah bahan nonteks menjadi teks atau field terlebih dahulu. Penulisan penjelasan serta pembuatan gambar atau video membutuhkan model atau langkah lain.

Lebih baik alias atau versi tetap?

Alias praktis untuk eksplorasi. Untuk alur berbasis ambang, evaluasi versi tetap yang didukung, catat model, dan validasi ulang ambang sebelum pindah versi. Model yang tersedia dapat berbeda antara gateway dan layanan langsung.

Sumber

• Referensi API TypeSafe
• Model, harga, alias, dan batas
• Memahami confidence
• Keterbatasan Jev 1.13