# Panduan API Jev

> Hubungkan API Jev lewat curl, Python, atau Node.js. Pelajari respons Choice, Score, Noul, autentikasi, batas konteks, rate limit, dan penanganan error.

- Canonical HTML: https://omniakey.com/id/blog/jev-api-guide
- Markdown: https://omniakey.com/id/blog/jev-api-guide.md
- Published: 2026-09-28 (updated 2026-10-24)
- Author: Kiki, COO at OmniaKey
- Language: id
- Category: API setup
- Reading time: 11 min
- All posts: https://omniakey.com/blog/llms.txt

---

**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 cara menggunakan API Jev untuk integrasi. Untuk kegunaan, harga, dan keterbatasan model, baca [penjelasan model Jev](https://omniakey.com/id/blog/jev-model-explained).

> **Diperiksa 24 Oktober 2026.** Kontrak berasal dari dokumentasi TypeSafe; rute gateway diperiksa terhadap implementasi OmniaKey. Contoh diperiksa secara offline, bukan lewat uji performa berbayar baru. Harga dan kuota layanan langsung tidak otomatis berlaku pada gateway.

## Pilih endpoint dan API key yang sesuai

|Layanan|Endpoint POST|Kredensial|
|-|-|-|
|OmniaKey|`https://api.omniakey.com/v1/alpha/search`|API key OmniaKey yang dapat mengakses `jev-latest`|
|TypeSafe langsung|`https://api.typesafe.ai/v1/systemone`|API key TypeSafe|

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](https://omniakey.com/id/jev-latest), 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)](https://docs.omniakey.com/en/quick-start).

## 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.

```json
{
  "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.

```bash
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

|Jenis|Yang ditentukan|Field jawaban|Makna|
|-|-|-|-|
|`choice`|Opsi dan deskripsinya, maksimal 255 opsi|`choice`, `probabilities`, `confidence`|Label pilihan dan distribusi probabilitas setiap opsi|
|`score`|Rubrik berurutan dengan 2–10 tingkat|`score`, `legend`, `probabilities`, `confidence`|Tingkat berbobot probabilitas, dapat berupa pecahan|
|`noul`|Pertanyaan ya/tidak, kriteria `true` / `false` opsional|`noul`|Probabilitas ya antara 0 dan 1, bukan boolean|

Respons juga memuat `model` serta `usage.input_tokens` / `usage.output_tokens`. Saat diperiksa, `jev-latest` mengarah ke `jev-1.14.0`. Alias bisa berubah, jadi catat versi yang benar-benar menjawab saat mengevaluasi hasil; jika harus tetap, tulis `jev-1.14.0`.

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.

```json
{
  "model": "jev-1.14.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
  }
}
```

## Cara menggunakan API Jev dengan 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.

```python
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))
```

```javascript
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](https://docs.typesafe.ai/api).

## 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](https://omniakey.com/id/blog/jev-model-explained) 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

|Status TypeSafe langsung|Pemeriksaan pertama|Tindakan|
|-|-|-|
|`401`|Key milik layanan yang benar dan header Bearer|Perbaiki kredensial; jangan ulang key tidak valid yang sama|
|`422`|Field wajib, tipe, dan bentuk `criteria`|Perbaiki field yang disebut dalam error|
|`429`|Batas permintaan atau token|Ikuti `Retry-After` jika ada; gunakan backoff eksponensial terbatas dengan jitter|
|`529`|Layanan sementara kelebihan beban|Batasi jumlah percobaan dan total waktu tunggu|

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](https://docs.typesafe.ai/api) menentukan schema langsung, sedangkan [halaman model](https://docs.typesafe.ai/models) menentukan harga dan kuotanya. Tabel endpoint membedakan kedua layanan.

### Bisakah Jev menerima gambar atau menulis teks?

Jev 1.14 menerima teks secara default dan mengembalikan keputusan bertipe. Ubah bahan nonteks menjadi teks atau field terlebih dahulu; input gambar di 1.14 ada di balik pengaturan eksperimental. 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](https://docs.typesafe.ai/api)
- [Model, harga, alias, dan batas](https://docs.typesafe.ai/models)
- [Memahami confidence](https://docs.typesafe.ai/confidence)
- [Keterbatasan Jev 1.13](https://docs.typesafe.ai/model-jaggedness/jev-1.13)