Dokumentasi

Panduan API Fkey

API kami kompatibel dengan OpenAI, sehingga Anda dapat memakai SDK resmi OpenAI hanya dengan mengganti base_url dan api_key.

Buat API Key

Base URL & Autentikasi

Semua request dikirim ke base URL berikut. Sertakan API key Anda pada header Authorization dengan skema Bearer.

text

Base URL : https://www.fkey.biz.id/api/v1
Endpoint : POST /chat/completions
           GET  /models
Header   : Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx

Penting

Jangan pernah menaruh API key di kode frontend atau repository publik. Simpan sebagai environment variable di server Anda.

Contoh Penggunaan

1. Non-streaming (OpenAI SDK):

chat.js

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FKEY_API_KEY,
  baseURL: "https://www.fkey.biz.id/api/v1",
});

// Non-streaming chat completion
const response = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Ringkas berita teknologi hari ini." }],
});

console.log(response.choices[0].message.content);
console.log("Token:", response.usage?.total_tokens);

2. Streaming SSE (OpenAI SDK):

stream.js

// Streaming response dengan OpenAI SDK (Node.js / Next.js)
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FKEY_API_KEY,
  baseURL: "https://www.fkey.biz.id/api/v1",
});

const stream = await client.chat.completions.create({
  model: "cc/claude-opus-5",
  messages: [{ role: "user", content: "Halo, berikan tips coding clean!" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

POST /chat/completions

Endpoint utama untuk chat completion. Mendukung streaming SSE dan parameter standar OpenAI.

Contoh cepat (cURL)

chat.sh

curl https://www.fkey.biz.id/api/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "Jelaskan apa itu API dalam satu paragraf." }
    ]
  }'

Contoh streaming (cURL)

stream.sh

curl -N https://www.fkey.biz.id/api/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cc/claude-opus-5",
    "messages": [
      { "role": "user", "content": "Tulis puisi singkat tentang senja." }
    ],
    "stream": true
  }'

# Flag -N mematikan buffering curl agar potongan SSE langsung tercetak.

Parameter lengkap (cURL)

chat-full.sh

curl https://www.fkey.biz.id/api/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cx/gpt-6-astra",
    "messages": [
      { "role": "system", "content": "Kamu adalah asisten yang ringkas." },
      { "role": "user", "content": "Ringkas berita teknologi hari ini." }
    ],
    "temperature": 0.7,
    "top_p": 0.9,
    "max_tokens": 500,
    "stream": false,
    "stream_options": { "include_usage": true }
  }'

SDK & bahasa lain

1. Non-streaming (OpenAI SDK):

chat.js

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FKEY_API_KEY,
  baseURL: "https://www.fkey.biz.id/api/v1",
});

// Non-streaming chat completion
const response = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Ringkas berita teknologi hari ini." }],
});

console.log(response.choices[0].message.content);
console.log("Token:", response.usage?.total_tokens);

2. Streaming SSE (OpenAI SDK):

stream.js

// Streaming response dengan OpenAI SDK (Node.js / Next.js)
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FKEY_API_KEY,
  baseURL: "https://www.fkey.biz.id/api/v1",
});

const stream = await client.chat.completions.create({
  model: "cc/claude-opus-5",
  messages: [{ role: "user", content: "Halo, berikan tips coding clean!" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Body request

Field yang didukung

model

wajib

ID model, mis. `auto` atau `cc/claude-opus-5`.

messages

wajib

Array pesan dengan role system/user/assistant.

stream

opsional

Set `true` untuk respons streaming SSE.

temperature

opsional

0–2. Mengatur kreativitas output.

top_p

opsional

0–1. Nucleus sampling.

max_tokens

opsional

Batas maksimum token output.

stop

opsional

String atau array string penanda berhenti.

stream_options

opsional

`{ include_usage: true }` agar usage dikirim di akhir stream.

Respons sukses (non-streaming)

json

{
  "id": "chatcmpl-9xYz...",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "auto",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Halo! Ada yang bisa saya bantu?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 18,
    "total_tokens": 30
  },
  "credit": {
    "cost": 1,
    "balance": 4989,
    "currency": "IDR",
    "unit": "credit"
  }
}

Biaya per request

Setiap respons menyertakan objek credit berisi cost (credit terpakai untuk request ini) dan balance (sisa saldo). Nilainya sama dengan header x-credit-cost dan x-credit-balance.

Saat streaming, objek credit dikirim sebagai satu chunk terakhir sebelum data: [DONE].

Header respons tambahan

text

x-credit-cost: 1
x-credit-balance: 4989
x-ratelimit-limit-requests: 60
x-ratelimit-remaining-requests: 59

Respons streaming (SSE)

text

data: {"id":"chatcmpl-9xYz...","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"chatcmpl-9xYz...","choices":[{"index":0,"delta":{"content":"Halo"}}]}

data: {"id":"chatcmpl-9xYz...","choices":[{"index":0,"delta":{"content":"!"}}]}

data: {"id":"chatcmpl-9xYz...","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":18,"total_tokens":30}}

data: {"object":"chat.completion.chunk","choices":[],"credit":{"cost":1,"balance":4989,"currency":"IDR","unit":"credit"}}

data: [DONE]

GET /models

Mengembalikan daftar model aktif beserta harga jual per 1 juta token. Harga dinyatakan dalam credit, di mana 1 credit = Rp1.

list-models.sh

curl https://www.fkey.biz.id/api/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

# Filter model yang mendukung Vision:
curl https://www.fkey.biz.id/api/v1/models \
  -H "Authorization: Bearer sk-your-api-key" \
  | jq '.data[] | select(.capabilities.vision == true) | .id'

Contoh respons JSON:

json

{
  "object": "list",
  "data": [
    {
      "id": "cc/claude-opus-5",
      "object": "model",
      "created": 1730000000,
      "owned_by": "Anthropic",
      "display_name": "Claude Opus 5",
      "description": "Konteks 200K. Mendukung input gambar.",
      "pricing": {
        "input_per_1m_credits": 1020,
        "output_per_1m_credits": 3060,
        "currency": "IDR",
        "unit": "credit"
      }
    },
    {
      "id": "auto",
      "object": "model",
      "created": 1730000000,
      "owned_by": "Fkey",
      "display_name": "Auto (Pilih Otomatis)",
      "description": "Router otomatis ke model terbaik.",
      "pricing": {
        "input_per_1m_credits": 100,
        "output_per_1m_credits": 300,
        "currency": "IDR",
        "unit": "credit"
      }
    }
  ]
}

Analisis Gambar (Vision)

Beberapa model mendukung input gambar (multimodal). Kirim gambar dengan mengubah content menjadi array part, lalu tambahkan part bertipe image_url.

Cek dukungan model

Tidak semua model menerima gambar. Gunakan model yang memiliki label Vision pada GET /models, misalnya cc/claude-opus-5, cx/gpt-5.6-sol, gemini/gemini-3.8-flash-high, atau gr/grok-4.7.

vision.js

// Kirim gambar via URL atau base64 data URI
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FKEY_API_KEY,
  baseURL: "https://www.fkey.biz.id/api/v1",
});

const response = await client.chat.completions.create({
  model: "cc/claude-opus-5", // gunakan model yang mendukung Vision
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Jelaskan isi gambar ini secara singkat." },
        {
          type: "image_url",
          image_url: { url: "https://example.com/foto.jpg" },
        },
      ],
    },
  ],
  max_tokens: 300,
});

console.log(response.choices[0].message.content);

Format content multimodal:

json

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Pertanyaan Anda tentang gambar" },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://contoh.com/gambar.jpg"
      }
    }
  ]
}

Contoh respons JSON:

json

{
  "id": "chatcmpl-21e67fbd-2c9c-4f41-a6fc-cd15f6596ae3",
  "object": "chat.completion",
  "model": "cc/claude-opus-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Gambar ini menampilkan sebuah foto berwarna pink."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 396,
    "completion_tokens": 13,
    "total_tokens": 468
  }
}

Catatan penting:

URL gambar harus dapat diakses publik, atau gunakan data URI base64 (data:image/jpeg;base64,...).
Gambar ikut dihitung sebagai token input, sehingga biaya request bertambah sesuai ukuran gambar.
Format yang umum didukung: JPEG, PNG, WebP, dan GIF. Batas ukuran bergantung pada model upstream.
Anda dapat mengirim beberapa gambar sekaligus dalam satu pesan dengan menambahkan lebih dari satu part image_url.

Sistem Credit & Biaya

Biaya setiap request dihitung dari jumlah token input dan output yang dikalikan harga model, lalu dibulatkan ke atas ke satuan credit terkecil.

Setiap model punya harga berbeda. Tarif dasar: 10.000 token = 1 credit (1 credit = Rp1), sehingga 1.000.000 token = 100 credit pada model termurah.

text

biaya = (input_tokens / 1.000.000) x harga_input
      + (output_tokens / 1.000.000) x harga_output

Contoh: model dengan harga_input 100 dan harga_output 300
  (tarif 10.000 token = 1 credit)
  input 1.200 token, output 800 token
  biaya = (1.200/1e6 x 100) + (800/1e6 x 300)
        = 0,12 + 0,24 = 0,36 credit  -> dibulatkan 1 credit

Model lebih canggih memakai credit lebih banyak per token,
jadi biaya request bergantung pada model yang dipilih.

Saldo dipotong secara atomic setelah respons selesai, sehingga tidak akan terjadi saldo minus walaupun ada request bersamaan. Semua mutasi tercatat di ledger transaksi.

Penanganan Error

Semua error mengikuti format OpenAI agar mudah ditangani oleh SDK.

json

{
  "error": {
    "message": "Saldo credit tidak cukup (saldo saat ini 0). Silakan top up di dashboard.",
    "type": "insufficient_quota",
    "code": "insufficient_credit"
  }
}

Status	Type	Keterangan
400	invalid_request_error	Body request tidak valid atau field wajib kosong.
401	authentication_error	API key tidak ada, tidak valid, atau sudah dicabut.
402	insufficient_quota	Saldo credit habis. Lakukan top up di dashboard.
403	permission_error	Akun diblokir atau model sedang tidak aktif.
404	invalid_request_error	Model tidak ditemukan di katalog.
429	rate_limit_error	Melebihi batas 60 request/menit.
502	server_error	Gagal menghubungi penyedia model (upstream).
503	service_unavailable	Layanan sedang maintenance.

Rate Limit

Setiap API key dibatasi 60 request per menit (nilai dapat berubah sesuai kebijakan admin). Setiap respons menyertakan header berikut:

text

x-ratelimit-limit-requests: 60
x-ratelimit-remaining-requests: 42
x-ratelimit-reset-requests: 2026-01-01T00:01:00.000Z

Integrasi AI Coding Tools

Karena API ini kompatibel OpenAI, Anda bisa memakainya di OpenCode, 9Router, Cline, Continue, Roo Code, Aider, dan tool lain yang mendukung provider OpenAI-compatible. Gunakan API key Fkey (bukan key upstream) dan base URL https://www.fkey.biz.id/api/v1.

Panduan langkah demi langkah (9Router, OpenCode, Claude Code, dan lainnya) tersedia sebagai file di repo.

docs/INTEGRASI.md

Termudah

OpenCode — impor otomatis

Endpoint ini mengembalikan konfigurasi OpenCode lengkap dengan semua model aktif dan API key Anda. Cukup satu perintah:

impor-otomatis.sh

# Buat folder config (lewati bila sudah ada)
mkdir -p ~/.config/opencode

# Tulis konfigurasi Fkey langsung ke OpenCode
curl -H "Authorization: Bearer sk-key-anda" \
     "https://www.fkey.biz.id/api/opencode/config?format=full" \
     > ~/.config/opencode/opencode.json

# Jalankan OpenCode, lalu ketik /models dan pilih model Fkey
opencode

Ingin menggabungkan dengan provider lain? Pakai ?format=provider lalu salin blok fkey ke dalam provider pada config Anda yang sudah ada.

ambil-blok-provider.sh

# Hanya blok provider (untuk digabung manual)
curl -H "Authorization: Bearer sk-key-anda" \
     "https://www.fkey.biz.id/api/opencode/config?format=provider"

OpenCode — konfigurasi manual

Salin ke ~/.config/opencode/opencode.json (Windows: %USERPROFILE%\\.config\\opencode\\opencode.json).

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "fkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Fkey",
      "options": {
        "baseURL": "https://www.fkey.biz.id/api/v1",
        "apiKey": "sk-key-anda"
      },
      "models": {
        "auto": { "name": "Auto (Pilih Otomatis)" },
        "cc/claude-opus-5": { "name": "Claude Opus 5" },
        "cx/gpt-6-astra": { "name": "GPT 6 Astra" }
      }
    }
  }
}

Script pembantu (repo ini)

Bila Anda meng-clone repo ini, ada script yang menarik seluruh model lalu menulis config secara otomatis (menggabungkan, tidak menimpa provider lain, dan membuat backup):

terminal

node scripts/setup-opencode.mjs --key sk-key-anda

# Opsi lain:
#   --base-url <url>    base URL API (default http://localhost:3000/api/v1)
#   --config <path>     lokasi opencode.json
#   --provider-id <id>  ID provider (default fkey)
#   --dry-run           lihat hasil tanpa menulis file

Panduan

9Router — pakai Fkey sebagai provider

9Router adalah gateway AI (lokal atau remote) dengan REST kompatibel OpenAI. Cara paling rapi memakai Fkey di dalamnya: daftarkan Fkey sebagai provider OpenAI-compatible, lalu arahkan semua tool ke satu endpoint 9Router. Tiga langkah:

1. Jalankan 9Router

jalankan-9router.sh

npm install -g 9router
9router

# Dashboard  : http://localhost:20128
# API gateway: http://localhost:20128/v1
# Cek status : curl http://localhost:20128/api/health   # {"ok":true}

2. Tambahkan Fkey sebagai provider

Di dashboard 9Router, buka menu Providers, tambahkan provider baru bertipe OpenAI-compatible (custom), lalu isi:

provider-fkey

Name     : Fkey
Base URL : https://www.fkey.biz.id/api/v1
API Key  : sk-key-anda   # API key Fkey dari dashboard, BUKAN key upstream

3. Arahkan tool Anda ke 9Router

Di Claude Code, Cursor, Cline, OpenCode, dan sejenisnya, set endpoint ke http://localhost:20128/v1 dan pakai API key dari dashboard 9Router. Nama model mengikuti katalog 9Router — jalankan GET /v1/models lalu pakai data[].id sebagai nilai model (mis. auto atau cc/claude-opus-5).

Verifikasi cepat

uji-lewat-9router.sh

# Lewat gateway 9Router (port 20128), bukan langsung ke Fkey
curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer sk-key-9router" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hi"}]}'

Kode error umum

Kode	Artinya
401	Set / perbarui API key 9Router (Dashboard → Keys).
400	Format model salah. Pastikan model ada di GET /v1/models.
503	Semua akun provider tidak tersedia. Tunggu retry-after atau tambah akun.
402	Dari sisi Fkey: saldo credit habis. Top up di dashboard Fkey.

Tool lain (Cline, Continue, Roo Code, Aider)

Tool	Provider / Mode	Base URL
Cline / Roo Code	OpenAI Compatible	https://www.fkey.biz.id/api/v1
Continue	openai	https://www.fkey.biz.id/api/v1
Aider	--openai-api-base	https://www.fkey.biz.id/api/v1
Zed	OpenAI Compatible	https://www.fkey.biz.id/api/v1
OpenAI SDK	base_url	https://www.fkey.biz.id/api/v1

Model yang dipakai harus nama yang sama seperti di GET /models, mis. auto, cc/claude-opus-5, atau gr/deepseek-v4.1-flash.

Siap mencoba sekarang?

Buat API key dan jalankan request pertama Anda dalam hitungan menit.

Mulai