Lompat ke konten utama
StableTerakhir diperbarui: 20 Okt 2026, 09.55

Universal AI Gateway & Reseller Token API

Universal AI Gateway adalah gerbang API berstandar OpenAI (OpenAI-compatible REST Gateway) terpadu di DagangBot. Fitur ini memungkinkan pemilik toko, pengembang aplikasi, pengguna n8n, LangChain, maupun sistem eksternal untuk membeli saldo Top-Up di DagangBot dan memanggil puluhan model kecerdasan buatan melalui satu alamat endpoint universal yang ringkas.

Stable

1. Ikhtisar & Keunggulan Utama

Banyak tim pengembang dan pelaku bisnis membutuhkan akses ke berbagai mesin komputasi AI (mencakup Chat Completions, Multimodal Vision, Image Generation, Voice STT/TTS, hingga Real-time Web Search) tanpa harus mengelola banyak tagihan kartu kredit internasional atau membuat kode integrasi yang berbeda untuk setiap penyedia.

  • Endpoint Universal & Pendek: Seluruh panggilan API cukup diarahkan ke Base URL https://dagangbot.web.id/v1 (atau alias /api/v1/ai). Kompatibel langsung dengan pustaka resmi OpenAI SDK di Node.js, Python, Go, PHP, hingga alat otomasi seperti n8n dan Cursor.
  • Delapan Kapabilitas dalam Satu Pintu: Mendukung penuh Chat Completions (termasuk Server-Sent Events stream: true), Vision (Image-to-Text), Text Embeddings, Image Generation, Text-to-Speech (TTS), Speech-to-Text (STT), Web Search, dan Web Fetch.
  • Manajemen Multi-API Key (dgb_ai_): Buat kunci API terpisah untuk setiap proyek, aplikasi, atau klien lengkap dengan pembatasan izin kapabilitas (capability scope), batas permintaan per menit (rate-limit RPM), dan pagu kuota token mandiri.
  • Model Pay-As-You-Go Murni: Dapat digunakan oleh seluruh tingkatan akun selama memiliki Saldo Bonus atau Saldo Top-Up yang mencukupi.
Kebijakan Saldo AI Gateway (Bonus Terlebih Dahulu)

Seluruh panggilan ke Universal AI Gateway (/v1/*) memakai Saldo Bonus terlebih dahulu sampai habis sebelum memotong Saldo Top-Up (paid_balance). Jika Saldo Bonus dan Saldo Top-Up Anda telah habis, permintaan API akan ditolak dengan kode status HTTP 402 Payment Required.

2. Daftar Endpoint Universal (/v1)

Seluruh endpoint di bawah ini menerima header autentikasi Authorization: Bearer dgb_ai_... atau X-API-Key: dgb_ai_...:

Metode & Path Endpoint Kapabilitas Satuan Tagihan Deskripsi Fungsi
GET /v1/models Semua Gratis Menampilkan daftar seluruh model AI aktif yang tersedia di katalog.
GET /v1/models/:kind Filter Jenis Gratis Menampilkan model berdasarkan jenis (embedding, image, tts, stt, search, fetch, image-to-text).
POST /v1/chat/completions chat / vision per_1k_tokens Percakapan teks multi-turn, analisis gambar (vision), dan streaming SSE (stream: true).
POST /v1/embeddings embedding per_1k_tokens Mengubah teks menjadi representasi vektor numerik untuk pencarian semantik atau RAG.
POST /v1/images/generations image per_image Menghasilkan gambar ilustrasi atau foto produk dari instruksi teks (prompt).
POST /v1/audio/speech tts per_1k_chars Mengubah teks menjadi berkas suara natural (Text-to-Speech).
POST /v1/audio/transcriptions stt per_request Menyalin rekaman suara (multipart/form-data) menjadi teks (Speech-to-Text).
POST /v1/search web_search per_request Melakukan pencarian informasi waktu nyata di internet untuk agen AI.
POST /v1/fetch web_fetch per_request Mengekstrak konten bersih dari sebuah halaman web publik menjadi teks terstruktur.

3. Panduan Langkah-demi-Langkah Penggunaan

Ikuti langkah berikut untuk mulai mengintegrasikan Universal AI Gateway ke aplikasi Anda:

Langkah 1: Mengisi Saldo Top-Up (Paid Balance)

  1. Masuk ke dasbor toko Anda dan buka menu Langganan & Dompet (/app/billing).
  2. Pilih nominal Top-Up Token dan selesaikan pembayaran melalui metode yang tersedia (QRIS, Virtual Account, atau Transfer).
  3. Pastikan nilai pada kartu Saldo Top-Up (Paid Balance) telah bertambah.

Langkah 2: Membuat API Key (dgb_ai_...)

  1. Buka menu AI & Otomasi → AI Gateway (API) (/app/ai-gateway).
  2. Pada tab API Keys, klik tombol Buat API Key Baru.
  3. Masukkan nama proyek (misalnya: Workflow n8n CS atau Aplikasi Kasir), atur batas RPM (default: 60 request/menit), dan tentukan batas kuota token jika diperlukan.
  4. Pilih kapabilitas yang diizinkan untuk kunci tersebut, lalu klik Buat API Key.
  5. Salin dan simpan kunci rahasia dgb_ai_... yang muncul di layar. Demi keamanan, kunci penuh hanya ditampilkan satu kali saat pembuatan.

Langkah 3: Memanggil Endpoint dari Aplikasi Anda

Gunakan cuplikan kode berikut untuk menghubungkan aplikasi Anda ke Base URL https://dagangbot.web.id/v1:

bash
curl -X POST https://dagangbot.web.id/v1/chat/completions \
  -H "Authorization: Bearer dgb_ai_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "conversational-v1",
    "messages": [
      {"role": "system", "content": "Kamu adalah asisten bisnis yang ramah."},
      {"role": "user", "content": "Tuliskan caption promosi kopi susu gula aren."}
    ],
    "stream": false
  }'

Untuk pengguna OpenAI SDK di Node.js / TypeScript:

typescript
import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://dagangbot.web.id/v1",
  apiKey: process.env.DAGANGBOT_AI_KEY, // dgb_ai_...
});

const completion = await openai.chat.completions.create({
  model: "conversational-v1",
  messages: [{ role: "user", content: "Halo dari DagangBot AI Gateway!" }],
});

4. Transparansi Perhitungan Biaya & Header Respons

Setiap panggilan yang berhasil ke endpoint /v1/* akan memotong Saldo Top-Up secara atomik dan menyertakan informasi pemotongan token langsung pada HTTP Response Header:

  • X-DagangBot-Charged-Tokens: Jumlah token yang didebit dari Saldo Top-Up Anda untuk panggilan tersebut.
  • X-DagangBot-Balance-After: Sisa Saldo Top-Up (paid_balance) Anda tepat setelah panggilan selesai.
  • X-DagangBot-Model: Identitas model dan kapabilitas yang menangani permintaan.

5. Kode Status & Pemecahan Masalah (Troubleshooting)

Kode HTTP & Kode Error Penyebab Utama Solusi Penanganan
401 invalid_api_key Header autentikasi kosong, tidak diawali dgb_ai_, sudah dicabut, atau kedaluwarsa. Periksa kembali header Authorization: Bearer dgb_ai_... dan pastikan status key AKTIF di dasbor.
402 insufficient_paid_balance Saldo Top-Up (paid_balance) bernilai 0 atau kurang dari tarif minimum model. Isi ulang Saldo Top-Up di menu Billing & Dompet. Ingat bahwa Saldo Bonus tidak dapat digunakan untuk API Gateway.
403 capability_forbidden API Key memanggil endpoint yang tidak dicentang pada izin kapabilitasnya. Edit API Key di menu /app/ai-gateway dan aktifkan kapabilitas yang sesuai (misalnya image atau web_search).
429 key_quota_exceeded Pemakaian akumulatif pada API Key tersebut telah mencapai nilai token_limit. Klik tombol Reset Kuota pada baris API Key di dasbor atau naikkan batas kuotanya.
429 rate_limit_exceeded Jumlah permintaan per menit melampaui batas rate_limit_rpm pada API Key. Kurangi frekuensi pengiriman request paralel atau naikkan nilai RPM pada konfigurasi API Key.

6. Referensi Terkait

content/docs/features/ai-gateway.mdx
Terakhir diperbarui: 20 Okt 2026, 09.55

Dokumentasi teknis DagangBot