Cara pakai KunciAI
KunciAI menyediakan API OpenAI-compatible untuk memanggil model AI dengan credit prabayar. Buat API key di dashboard, lalu arahkan aplikasi ke base URL https://kunciai.id/v1.
Quickstart
Semua request memakai header Authorization: Bearer <API key>. Simpan key sebagai environment variable.
# Windows PowerShell
$env:KUNCIAI_API_KEY="key-kamu"
# macOS/Linux
export KUNCIAI_API_KEY="key-kamu"Lalu buat API key di Dashboard → API Keys dan panggil endpoint pertama:
curl https://kunciai.id/v1/chat/completions \
-H "Authorization: Bearer $KUNCIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"kunciai/deepseek-v4-flash","messages":[{"role":"user","content":"Halo"}]}'Ganti model dengan ID dari katalog model. Contoh yang sedang aktif: kunciai/claude-opus-4.6.
API
Base URL: https://kunciai.id/v1. Endpoint yang tersedia:
| Method | Path | Keterangan |
|---|---|---|
GET | /v1/models | Daftar model yang bisa dipakai akun kamu. |
POST | /v1/chat/completions | Chat completion, mendukung stream. |
POST | /v1/images/generations | Generate gambar dari teks (format OpenAI). Lihat Gambar. |
POST | /v1/videos/generations | Mulai generate video dari teks atau gambar (async). Lihat Video. |
POST | /v1/videos/motion-control | Animasikan karakter di foto dengan gerakan dari video referensi (async). Lihat Motion Control. |
GET | /v1/videos/generations/{id} | Cek status dan ambil URL video (termasuk motion control). |
Body mengikuti format OpenAI: model, messages, dan opsi umum seperti temperature, max_tokens, serta stream. Field yang dikirim diteruskan ke upstream.
Payload maksimum 1 MB. Balasan error memakai bentuk {"error":{"message":"...","code":"..."}}.
Streaming
Kirim stream: true untuk menerima Server-Sent Events. KunciAI meneruskan event upstream dan menutup dengan [DONE].
curl -N https://kunciai.id/v1/chat/completions \
-H "Authorization: Bearer $KUNCIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"kunciai/deepseek-v4-flash","messages":[{"role":"user","content":"Halo"}],"stream":true}'Saat streaming, KunciAI menambahkan stream_options.include_usage agar pemakaian token akhir terkirim dan credit bisa dihitung tepat.
Billing
Credit dihitung dari input, cached input, dan output aktual: ceil((input-cache)*tarif_input+cache*tarif_cache+output*tarif_output). Tarif per model bisa dilihat di katalog.
Setiap request menahan reserve sementara. Setelah usage diterima, biaya aktual disettle dan sisa reserve dikembalikan. Request yang gagal sebelum ada output tidak dikenai biaya.
Isi saldo lewat paket credit di Dashboard → Billing.
Gambar
Buat gambar dari teks lewat POST /v1/images/generations. Formatnya mengikuti OpenAI, jadi bisa langsung dipakai dengan client.images.generate() dari SDK OpenAI.
curl https://kunciai.id/v1/images/generations \
-H "Authorization: Bearer $KUNCIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"kunciai/nano-banana-2-lite","prompt":"kucing astronot di bulan, gaya ilustrasi","size":"1792x1024"}'import os
from openai import OpenAI
client = OpenAI(base_url="https://kunciai.id/v1", api_key=os.environ["KUNCIAI_API_KEY"])
result = client.images.generate(
model="kunciai/nano-banana-2-lite",
prompt="kucing astronot di bulan, gaya ilustrasi",
size="1024x1024",
)
print(result.data[0].url)| Field | Keterangan |
|---|---|
model | ID model gambar (tabel di bawah). Default kunciai/nano-banana-2-lite. |
prompt | Deskripsi gambar, maksimal 4000 karakter. Wajib. |
n | Jumlah gambar, 1-4. Default 1. |
size | Contoh 1024x1024, 1792x1024 (landscape), 1024x1792 (potret). Dipetakan ke rasio yang didukung model. |
aspect_ratio | Opsional, mengalahkan size. Contoh 16:9, 9:16, auto (Seedream). |
response_format | url (default) atau b64_json. |
reference_images | Opsional, array URL https:// untuk image-to-image. |
| Model | Credit / gambar | Rupiah / gambar | Maks. referensi |
|---|---|---|---|
kunciai/nano-banana-2-lite | 166.667 | Rp74 – Rp167 | 10 |
kunciai/nano-banana-2 | 166.667 | Rp74 – Rp167 | 10 |
kunciai/nano-banana-pro | 166.667 | Rp74 – Rp167 | 10 |
kunciai/qwen-image | 500.000 | Rp222 – Rp500 | 3 |
kunciai/seedream-4.0 | 500.000 | Rp222 – Rp500 | 6 |
kunciai/seedream-4.5 | 500.000 | Rp222 – Rp500 | 6 |
kunciai/seedream-5.0-lite | 500.000 | Rp222 – Rp500 | 6 |
kunciai/seedream-5.0-pro | 500.000 | Rp222 – Rp500 | 10 |
kunciai/kling-3.0 | 500.000 | Rp222 – Rp500 | 1 |
kunciai/kling-o3 | 500.000 | Rp222 – Rp500 | 1 |
kunciai/gpt-image-2.0 | 500.000 | Rp222 – Rp500 | 9 |
kunciai/gpt-image-2.5-flare | 500.000 | Rp222 – Rp500 | 16 |
kunciai/gpt-image-2.5-sunburst | 500.000 | Rp222 – Rp500 | 16 |
Hanya gambar yang berhasil dibuat yang ditagih. Jumlah credit yang terpakai dikirim di header x-kunciai-credits. URL gambar hanya berlaku sementara (sekitar 6 jam), jadi segera unduh dan simpan gambar yang Anda butuhkan, atau gunakan response_format: "b64_json".
Video
Video dibuat secara async karena butuh beberapa menit. Kirim POST /v1/videos/generations untuk mendapat id dengan status processing, lalu cek GET /v1/videos/generations/{id} berkala sampai status completed (ada url) atau failed.
# 1. Mulai proses video (async)
curl https://kunciai.id/v1/videos/generations \
-H "Authorization: Bearer $KUNCIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"kunciai/veo-3.1-lite","prompt":"drone terbang di atas sawah saat matahari terbit","aspect_ratio":"landscape","resolution":"720p"}'
# 2. Cek status sampai "completed" (ulangi tiap ~10 detik)
curl https://kunciai.id/v1/videos/generations/VIDEO_ID \
-H "Authorization: Bearer $KUNCIAI_API_KEY"import os, time, requests
base = "https://kunciai.id/v1"
headers = {"Authorization": f"Bearer {os.environ['KUNCIAI_API_KEY']}"}
job = requests.post(f"{base}/videos/generations", headers=headers, json={
"model": "kunciai/veo-3.1-lite",
"prompt": "drone terbang di atas sawah saat matahari terbit",
"aspect_ratio": "landscape",
}).json()
while job["status"] == "processing":
time.sleep(10)
job = requests.get(f"{base}/videos/generations/{job['id']}", headers=headers).json()
print(job["status"], job.get("url") or job.get("error"))| Field | Keterangan |
|---|---|
model | ID model video (tabel di bawah). Default kunciai/veo-3.1-lite. |
prompt | Deskripsi video, maksimal 4000 karakter. Wajib. |
aspect_ratio | Opsional. Veo/Omni: landscape atau portrait. PixVerse: 16:9, 9:16, 1:1, dst. |
resolution | Opsional, contoh 720p atau 1080p. Menentukan tarif. |
duration | Opsional, detik. Hanya model yang punya pilihan durasi. |
image | Opsional, gambar pembuka (image-to-video): URL https:// atau data URI base64. |
reference_images | Opsional, array URL https://. Lebih dari satu gambar memakai mode reference-to-video. |
{
"id": "VIDEO_ID",
"object": "video.generation",
"model": "kunciai/veo-3.1-lite",
"status": "completed",
"credits": 1500000,
"url": "https://.../video.mp4"
}| Model | Resolusi | Credit / video | Rupiah / video |
|---|---|---|---|
kunciai/veo-3.1-lite | 720p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/veo-3.1-lite | 1080p | 2.500.000 | Rp1.111 – Rp2.500 |
kunciai/gemini-omni-flash | 720p | 5.000.000 | Rp2.222 – Rp5.000 |
kunciai/v5 | 360p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v5 | 540p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v5 | 720p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v5 | 1080p | 2.500.000 | Rp1.111 – Rp2.500 |
kunciai/v5.5 | 360p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v5.5 | 540p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v5.5 | 720p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v5.5 | 1080p | 2.500.000 | Rp1.111 – Rp2.500 |
kunciai/v5.6 | 360p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v5.6 | 540p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v5.6 | 720p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v5.6 | 1080p | 2.500.000 | Rp1.111 – Rp2.500 |
kunciai/v6 | 360p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v6 | 540p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v6 | 720p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/v6 | 1080p | 2.500.000 | Rp1.111 – Rp2.500 |
kunciai/pixverse-c1 | 360p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/pixverse-c1 | 540p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/pixverse-c1 | 720p | 1.500.000 | Rp667 – Rp1.500 |
kunciai/pixverse-c1 | 1080p | 2.500.000 | Rp1.111 – Rp2.500 |
Saldo ditahan saat request dikirim dan baru ditagih saat video selesai. Jika status failed, saldo dikembalikan penuh. Daftar model video beserta opsi validnya juga ada di GET /v1/models (type: "video"). Segera unduh video karena URL hanya berlaku sementara.
Motion Control
Motion Control menganimasikan karakter di sebuah foto agar bergerak persis seperti orang di video referensi (misalnya joget atau gerakan tangan). Kirim POST /v1/videos/motion-control, lalu cek status di GET /v1/videos/generations/{id} seperti video biasa.
# 1. Mulai motion control (async): foto karakter + video gerakan referensi
curl https://kunciai.id/v1/videos/motion-control \
-H "Authorization: Bearer $KUNCIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"character_image":"https://contoh.com/karakter.png","motion_video":"https://contoh.com/joget.mp4","resolution":"720p"}'
# 2. Cek status di endpoint yang sama dengan video
curl https://kunciai.id/v1/videos/generations/VIDEO_ID \
-H "Authorization: Bearer $KUNCIAI_API_KEY"import os, time, requests
base = "https://kunciai.id/v1"
headers = {"Authorization": f"Bearer {os.environ['KUNCIAI_API_KEY']}"}
job = requests.post(f"{base}/videos/motion-control", headers=headers, json={
"character_image": "https://contoh.com/karakter.png",
"motion_video": "https://contoh.com/joget.mp4",
}).json()
while job.get("status") == "processing":
time.sleep(10)
job = requests.get(f"{base}/videos/generations/{job['id']}", headers=headers).json()
print(job.get("status"), job.get("url") or job.get("error"))| Field | Keterangan |
|---|---|
character_image | URL https:// publik foto karakter (jpg/png/webp). Wajib. |
motion_video | URL https:// publik video gerakan referensi (mp4/mov/webm, maks. 45 MB). Wajib. |
resolution | Opsional: 360p, 540p, atau 720p. |
Tarif flat 1.500.000 credit per video (Rp667 – Rp1.500), untuk resolusi apa pun. Respons memakai bentuk yang sama dengan video, dengan model: "kunciai/motion-control".
File harus bisa diunduh langsung dari URL tanpa login (bukan link halaman Google Drive). Saldo ditahan saat submit, ditagih saat selesai, dan dikembalikan penuh jika failed.
Error
Respons error memakai HTTP status standar dengan kode yang bisa ditangani program.
| Status | Code | Arti |
|---|---|---|
401 | invalid_api_key | API key tidak valid atau dicabut. |
402 | insufficient_credits | Saldo tidak cukup untuk reserve. |
404 | model_not_found | Model tidak ada atau tidak tersedia. |
413 | payload_too_large | Body melebihi 10.000.000 karakter. |
404 | video_job_not_found | ID video tidak ada atau bukan milik akun kamu. |
502 | upstream_error | Upstream tidak dapat dihubungi. |
502 | video_submit_failed | Video gagal dimulai. Saldo dikembalikan. |
400 | invalid_character_image / invalid_motion_video | Media motion control bukan URL https:// yang valid. |
502 | motion_submit_failed | Motion control gagal dimulai. Saldo dikembalikan. |
503 | upstream_unconfigured | Layanan upstream belum siap. |
Integrasi
Karena OpenAI-compatible, sebagian besar tool bisa diarahkan ke KunciAI dengan base URL https://kunciai.id/v1 dan API key kamu. Tutorial langkah demi langkah ada di Panduan.
OpenCode
Simpan key sebagai environment variable, lalu buat opencode.json di folder proyek.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"kunciai": {
"npm": "@ai-sdk/openai-compatible",
"name": "KunciAI",
"options": {
"baseURL": "https://kunciai.id/v1",
"apiKey": "{env:KUNCIAI_API_KEY}"
},
"models": {
"kunciai/deepseek-v4-flash": {
"name": "DeepSeek V4 Flash"
}
}
}
},
"model": "kunciai/deepseek-v4-flash"
}Jalankan opencode. Tambahkan model lain dari katalog ke bagian models bila perlu.
- Claude CodeArahkan base URL ke
https://kunciai.id/v1dan pakai API key KunciAI. - Qwen CodeSet base URL
https://kunciai.id/v1pada konfigurasi provider. - AiderJalankan dengan
--openai-api-base https://kunciai.id/v1. - ContinuePilih provider OpenAI-compatible, isi base URL dan API key.
- ClinePilih OpenAI Compatible dan isi base URL serta API key.
- PythonPakai SDK OpenAI dengan
base_url="https://kunciai.id/v1". - 9RouterTambahkan provider KunciAI di router lokal, lalu arahkan tool ke router.