Keural API

Panggil model yang terdaftar di Keural dengan format OpenAI Chat Completions.

Base URL memiliki bentuk https://<public API domain for each environment>/llm/v1. Domain API publik berbeda di setiap lingkungan, jadi tanyakan kepada administrator.

Path untuk embedding, pembuatan gambar, suara, dan Responses API tidak didukung. Permintaan ke path tersebut dikembalikan 404.

Alur penggunaanSalin tautan judul

PersiapanSalin tautan judul

Menerbitkan API keySalin tautan judul

1. Di menu akun, buka Pengaturan → API. Di aplikasi desktop dan mobile, menu ini ada di bagian Alat.
2. Di tab API keys, pilih workspace pemilik kunci (pribadi atau organisasi) dan Model ID.
3. Jika perlu, tentukan Tanggal kedaluwarsa kunci baru. Jika dikosongkan, kunci berlaku sampai dicabut.
4. Klik Terbitkan kunci, lalu salin kunci dengan Salin kunci dan simpan. Kunci lengkap hanya ditampilkan sekali saat diterbitkan.

• Kunci terikat pada workspace yang dipilih dan satu model. Pemakaian dihitung atas nama orang yang menerbitkan kunci.
• Setiap workspace dan model hanya memiliki satu kunci. Jika memerlukan kunci baru, rotasi atau cabut kunci yang ada.
• Jika kunci hilang, terbitkan ulang. Setelah diterbitkan ulang, kunci lama langsung tidak dapat dipakai.
• Jika tidak ada model yang dapat diterbitkan, periksa pengaturan visibilitas model, paket, dan izin API organisasi bersama administrator.

Izin API anggota organisasiSalin tautan judul

Khusus pemilik dan admin organisasi. Agar anggota dapat menerima kunci di workspace organisasi, admin harus mengizinkannya terlebih dahulu. Nilai default untuk semua anggota adalah diblokir.

Manajemen organisasi → Organization API terdiri dari tiga bagian berikut. Jika menu ini tidak ada, fitur API nonaktif atau akun Anda tidak punya izin manajemen organisasi.

Jika anggota keluar atau dikeluarkan dari organisasi, kunci yang diterimanya dari organisasi akan dicabut otomatis.

Menghubungkan ke klienSalin tautan judul

Masukkan tiga nilai berikut ke aplikasi yang kompatibel dengan OpenAI API (klien chat, ekstensi IDE, alat otomasi, dan lainnya).

1. Di pengaturan aplikasi, tambahkan Koneksi kompatibel OpenAI (Connection).
2. Masukkan Base URL dan API Key, lalu simpan.
3. Pilih model dari daftar model. Daftar hanya menampilkan satu model, yaitu model yang terhubung ke kunci.
4. Kirim pesan singkat dan pastikan respons diterima.

Format permintaan adalah sebagai berikut.

Permintaan pertamaSalin tautan judul

export KEURAL_API_KEY='kunci_yang_diterbitkan'
export KEURAL_BASE_URL='https://<domain API publik per lingkungan>/llm/v1'
export MODEL_ID='model ID dari layar penerbitan'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Halo.\"}]}"

Nilai model pada body permintaan harus sama dengan model ID yang terhubung ke kunci. Jika ada awalan path seperti provider/ID model, bagian setelah / terakhir yang dibandingkan. Jika tidak sama, API mengembalikan 403. Di respons, model selalu berisi model ID dari kunci.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "Halo."}],
)
print(res.choices[0].message.content)

Field permintaan yang didukungSalin tautan judul

Hanya 18 field level atas berikut yang diterima. Field lain menghasilkan 400. Field opsional yang bernilai null diperlakukan sebagai tidak dikirim.

PesanSalin tautan judul

• Pesan tool hanya membalas satu kali untuk setiap id di tool_calls sebelumnya.
• Bagian gambar (image_url) hanya dimasukkan ke pesan user untuk model yang menerima gambar. Gunakan alamat http atau https, atau data URI base64 berformat PNG, JPEG, GIF, atau WebP. detail berupa auto · low · high.

BodySalin tautan judul

Jika aturan body dilanggar, hasilnya 400 dan param berisi body.

StreamingSalin tautan judul

Tambahkan "stream": true ke permintaan untuk menerima respons melalui SSE. Chunk dikirim sebagai event data: ..., dan di akhir dikirim data: [DONE]. Jika menambahkan "stream_options": {"include_usage": true}, satu chunk penggunaan token tambahan dikirim tepat sebelum [DONE].

Saat include_usage diisi, setiap chunk berisi usage: null, dan chunk penggunaan terakhir memiliki choices berupa array kosong. Respons non-streaming hanya berisi usage jika jumlah token input dan output sudah terkonfirmasi.

ID respons berformat chatcmpl-<x-request-id>. Setiap respons menyertakan header x-request-id.

Jika terjadi error saat streaming, event data: yang berisi JSON error dikirim, lalu koneksi berakhir tanpa [DONE]. Jika satu chunk melebihi 1 MiB atau respons melebihi 16 MiB, stream berakhir dengan 503.

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Halo.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

Batas penggunaanSalin tautan judul

Permintaan dibatasi per pengguna, organisasi, dan model, berdasarkan jumlah permintaan bersamaan, permintaan per menit (RPM), dan token per menit (TPM). Nilai sebenarnya berbeda di setiap lingkungan.

Token per menit dikurangi di muka saat permintaan diterima. Input dihitung 1 token per 4 karakter bahasa Inggris, dan 1 token per karakter untuk bahasa lain. Satu gambar dihitung 2.000 token. Output dikurangkan sebesar max_tokens (maksimal 4.096), jadi jika Anda hanya menetapkan batas output yang diperlukan, sisa kuota akan lebih besar.

Mengelola kunciSalin tautan judul

Pada tab API keys di Pengaturan → API, periksa status kunci (valid · kedaluwarsa · dicabut), lalu terbitkan ulang atau cabut kunci.

Kunci berupa string 51 karakter yang diawali krl_llm_. Setiap workspace hanya memiliki satu kunci. Jika sudah ada, kunci diterbitkan ulang. Tanggal kedaluwarsa hanya dapat ditetapkan setelah hari ini.

Memeriksa penggunaanSalin tautan judul

Permintaan API dan penggunaan token dapat dilihat di dua tempat berikut.

Kondisi pencarianSalin tautan judul

Atur kondisi, lalu klik Cari. Untuk memuat permintaan terbaru, klik Segarkan.

Nilai yang tampil di layarSalin tautan judul

• Rentang waktu yang diterapkan: rentang yang benar-benar dicari. Jika waktu dikosongkan atau melebihi 90 hari, rentang yang disesuaikan server akan ditampilkan.
• Jumlah permintaan dan Token input · Token output · Total token: hanya menjumlahkan nilai yang sudah terkonfirmasi. Token yang belum terkonfirmasi ditampilkan sebagai Belum dikonfirmasi.
• Daftar permintaan: setiap permintaan ditampilkan dalam satu baris dengan waktu permintaan, Model ID, status permintaan, serta token input, output, dan total. Setiap halaman menampilkan 20 permintaan. Pindah halaman dengan Sebelumnya dan Berikutnya.

Klik Detail permintaan pada baris untuk menampilkan nilai berikut.

Permintaan streaming dicatat penggunaannya meskipun stream_options.include_usage tidak diisi. Jika permintaan terputus di tengah jalan, statusnya bisa tetap Sebagian terkonfirmasi atau Belum dikonfirmasi.

Format errorSalin tautan judul

Error dikembalikan dalam format yang kompatibel dengan OpenAI.

{
  "error": {
    "message": "Deskripsi error yang bisa dibaca manusia",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type ditentukan oleh kode status, dan code menunjukkan penyebabnya.

Pemecahan masalahSalin tautan judul

Jika belum teratasi, hubungi administrator dengan menyertakan informasi berikut. Jangan kirim isi kunci atau prompt.

• Waktu kejadian
• Model ID yang dipakai
• Nama dan versi aplikasi klien
• x-request-id dari header respons
• Pesan error yang tampil di layar