Mulai menggunakan SANSAI API

1. Buat akun

Daftar gratis di portal dengan email, akun Google, atau akun Facebook. Pendaftaran dengan email memerlukan verifikasi lewat tautan yang dikirim ke kotak masuk Anda; tautan verifikasi dan pemulihan password hanya dapat dipakai sekali dan berlaku 30 menit. Lupa password? Gunakan Minta pemulihan password di halaman masuk portal; reset password mencabut sesi lama.

Sesi dilindungi cookie HttpOnly/SameSite, pemeriksaan CSRF/origin, dan pembatasan percobaan login. Akun Google atau Facebook dikenali dari identitas penyedia tersebut; email yang sama tidak otomatis menggabungkan akun. Untuk mengaitkan Google atau Facebook ke akun email yang sudah ada, masuk dulu lalu buka menu Akun → Hubungkan Google (atau Facebook); pengaitan meminta konfirmasi password. Jangan pernah mengirim password lewat chat atau email.

Paket Free dan Pro

Pro: Rp29.000 per 30 hari atau Rp290.000 per 365 hari, dibayar lewat Xendit dari kartu Paket Saya di portal. Tidak diperpanjang otomatis; membayar lagi menambah masa aktif, dan email pengingat dikirim tiga hari sebelum berakhir. Detail ada di Ketentuan Layanan.

Social Studio dan Motion Studio

Social Studio: buat draf (sendiri atau dengan AI), setujui, lalu jadwalkan terbit ke Blogger, YouTube, dan Facebook Page. Panduan langkah demi langkah: artikel Social Studio.

Motion Studio: ubah naskah menjadi video teks bergerak (9:16, 16:9, 1:1) lalu tekan Unduh video; video direkam di browser Anda. Panduan: artikel Motion Studio.

2. Buat key dengan scope minimum

Di portal, centang hanya izin yang dibutuhkan lalu pilih Buat API key. Scope diperiksa di server dan tidak dapat dilewati hanya dengan mengubah UI.

Secret lengkap hanya ditampilkan saat key dibuat. Salin saat itu ke password manager/secret manager. Jangan menaruhnya di source control, URL, screenshot, log, atau browser storage. Portal tidak dapat mengambil secret lama kembali.

3. Gunakan chat API

Body menerima input wajib (1–12.000 karakter) dan provider opsional bernilai openai atau wiro. Tanpa provider, server memakai pilihan default konfigurasi.

curl -X POST https://sansai.id/api/v1/chat \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"input":"Halo, SANSAI!"}'

Bentuk respons sukses: {"id":"…","provider":"…","model":"…","output":"…"}. Contoh nilai ini menunjukkan field response, bukan klaim bahwa provider aktif.

4. Buat dan periksa job media

Pengajuan menerima body {"prompt":"…"} (1–4.000 karakter) dan membutuhkan scope media:create. Ini dapat memanggil provider berbayar.

curl -X POST https://sansai.id/api/v1/media/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"A calm landscape"}'

Respons sukses berbentuk {"id":"…","provider":"wiro","status":"submitted"}. Simpan ID job secara aman. Untuk membaca status, output, dan metadata, key yang sama harus memiliki media:read:

curl https://sansai.id/api/v1/media/jobs/JOB_ID \
  -H 'Authorization: Bearer YOUR_API_KEY'

Job lama tanpa catatan pemilik dan job milik key lain tidak dapat dibaca melalui API SANSAI.

Jika pengelola mengonfigurasi OPENAI_API_KEY dan OPENAI_IMAGE_MODEL, OpenAI juga dapat menghasilkan satu PNG melalui POST /api/v1/media/openai/images menggunakan scope media:create. Respons memuat PNG base64 hingga 12 MiB; perlakukan sebagai data privat dan jangan simpan di log. Permintaan ini dapat dikenai biaya provider. Ketersediaan endpoint bergantung pada konfigurasi serta versi backend yang aktif.

5. Pantau usage dan kuota

Scope usage:read diperlukan. Endpoint hanya menampilkan key terautentikasi, dengan jumlah cumulative dan current-window bila kuota dikonfigurasi.

curl https://sansai.id/api/v1/usage \
  -H 'Authorization: Bearer YOUR_API_KEY'

Bentuk respons berisi keyId, objek chat dan media (field limit, windowMs, used, windowUsed), totalRequests, serta updatedAt. Nilai limit/window dapat null bila kebijakan tidak aktif. Kuota bukan batas biaya atau sistem billing.

Agent uji di portal

Bagian Agent Uji SANSAI pada dashboard adalah percakapan untuk membantu memahami API dan mencoba prompt; agent ini tidak menjalankan tools atau tindakan akun. Pilih OpenAI atau Wiro, masukkan API key dengan scope chat:generate, lalu kirim pesan secara eksplisit. Pilihan provider, pesan, dan maksimal enam percakapan terakhir dikirim ke provider pada setiap permintaan. Riwayat hanya berada sementara di tab browser dan dapat dihapus; permintaan dapat menimbulkan biaya.

Bagian uji gambar memakai API key yang sama, mengirim prompt ke provider pilihan, dan memerlukan scope media:create; status dan hasil job Wiro juga memerlukan media:read. Jangan menggunakan API key produksi di komputer bersama atau membagikan hasil privat.

6. Pahami respons error

7. Cabut key yang tidak diperlukan

Pilih Cabut pada daftar key di portal. Key revoked langsung gagal autentikasi dan tidak dapat dipulihkan; buat key baru dengan scope minimum jika akses diperlukan kembali.

Administrator dapat membuat akun, menerbitkan/mencabut key, mengatur scope dan quota, serta melihat audit melalui panel admin. Viewer hanya dapat membaca data administrasi; perubahan memerlukan role admin.