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:

MethodPathKeterangan
GET/v1/modelsDaftar model yang bisa dipakai akun kamu.
POST/v1/chat/completionsChat completion, mendukung stream.
POST/v1/images/generationsGenerate gambar dari teks (format OpenAI). Lihat Gambar.
POST/v1/videos/generationsMulai generate video dari teks atau gambar (async). Lihat Video.
POST/v1/videos/motion-controlAnimasikan 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)
FieldKeterangan
modelID model gambar (tabel di bawah). Default kunciai/nano-banana-2-lite.
promptDeskripsi gambar, maksimal 4000 karakter. Wajib.
nJumlah gambar, 1-4. Default 1.
sizeContoh 1024x1024, 1792x1024 (landscape), 1024x1792 (potret). Dipetakan ke rasio yang didukung model.
aspect_ratioOpsional, mengalahkan size. Contoh 16:9, 9:16, auto (Seedream).
response_formaturl (default) atau b64_json.
reference_imagesOpsional, array URL https:// untuk image-to-image.
ModelCredit / gambarRupiah / gambarMaks. referensi
kunciai/nano-banana-2-lite166.667Rp74 – Rp16710
kunciai/nano-banana-2166.667Rp74 – Rp16710
kunciai/nano-banana-pro166.667Rp74 – Rp16710
kunciai/qwen-image500.000Rp222 – Rp5003
kunciai/seedream-4.0500.000Rp222 – Rp5006
kunciai/seedream-4.5500.000Rp222 – Rp5006
kunciai/seedream-5.0-lite500.000Rp222 – Rp5006
kunciai/seedream-5.0-pro500.000Rp222 – Rp50010
kunciai/kling-3.0500.000Rp222 – Rp5001
kunciai/kling-o3500.000Rp222 – Rp5001
kunciai/gpt-image-2.0500.000Rp222 – Rp5009
kunciai/gpt-image-2.5-flare500.000Rp222 – Rp50016
kunciai/gpt-image-2.5-sunburst500.000Rp222 – Rp50016

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"))
FieldKeterangan
modelID model video (tabel di bawah). Default kunciai/veo-3.1-lite.
promptDeskripsi video, maksimal 4000 karakter. Wajib.
aspect_ratioOpsional. Veo/Omni: landscape atau portrait. PixVerse: 16:9, 9:16, 1:1, dst.
resolutionOpsional, contoh 720p atau 1080p. Menentukan tarif.
durationOpsional, detik. Hanya model yang punya pilihan durasi.
imageOpsional, gambar pembuka (image-to-video): URL https:// atau data URI base64.
reference_imagesOpsional, 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"
}
ModelResolusiCredit / videoRupiah / video
kunciai/veo-3.1-lite720p1.500.000Rp667 – Rp1.500
kunciai/veo-3.1-lite1080p2.500.000Rp1.111 – Rp2.500
kunciai/gemini-omni-flash720p5.000.000Rp2.222 – Rp5.000
kunciai/v5360p1.500.000Rp667 – Rp1.500
kunciai/v5540p1.500.000Rp667 – Rp1.500
kunciai/v5720p1.500.000Rp667 – Rp1.500
kunciai/v51080p2.500.000Rp1.111 – Rp2.500
kunciai/v5.5360p1.500.000Rp667 – Rp1.500
kunciai/v5.5540p1.500.000Rp667 – Rp1.500
kunciai/v5.5720p1.500.000Rp667 – Rp1.500
kunciai/v5.51080p2.500.000Rp1.111 – Rp2.500
kunciai/v5.6360p1.500.000Rp667 – Rp1.500
kunciai/v5.6540p1.500.000Rp667 – Rp1.500
kunciai/v5.6720p1.500.000Rp667 – Rp1.500
kunciai/v5.61080p2.500.000Rp1.111 – Rp2.500
kunciai/v6360p1.500.000Rp667 – Rp1.500
kunciai/v6540p1.500.000Rp667 – Rp1.500
kunciai/v6720p1.500.000Rp667 – Rp1.500
kunciai/v61080p2.500.000Rp1.111 – Rp2.500
kunciai/pixverse-c1360p1.500.000Rp667 – Rp1.500
kunciai/pixverse-c1540p1.500.000Rp667 – Rp1.500
kunciai/pixverse-c1720p1.500.000Rp667 – Rp1.500
kunciai/pixverse-c11080p2.500.000Rp1.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"))
FieldKeterangan
character_imageURL https:// publik foto karakter (jpg/png/webp). Wajib.
motion_videoURL https:// publik video gerakan referensi (mp4/mov/webm, maks. 45 MB). Wajib.
resolutionOpsional: 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.

StatusCodeArti
401invalid_api_keyAPI key tidak valid atau dicabut.
402insufficient_creditsSaldo tidak cukup untuk reserve.
404model_not_foundModel tidak ada atau tidak tersedia.
413payload_too_largeBody melebihi 10.000.000 karakter.
404video_job_not_foundID video tidak ada atau bukan milik akun kamu.
502upstream_errorUpstream tidak dapat dihubungi.
502video_submit_failedVideo gagal dimulai. Saldo dikembalikan.
400invalid_character_image / invalid_motion_videoMedia motion control bukan URL https:// yang valid.
502motion_submit_failedMotion control gagal dimulai. Saldo dikembalikan.
503upstream_unconfiguredLayanan 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/v1 dan pakai API key KunciAI.
  • Qwen CodeSet base URL https://kunciai.id/v1 pada 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.