<SYSTEM>This is the full developer documentation for Vikey</SYSTEM>

# Pengenalan

> Vikey adalah satu API key untuk Claude, GPT, DeepSeek, dan model AI lain, kompatibel dengan format OpenAI dan Anthropic, bayar dalam Rupiah.

Vikey adalah API inference AI. Dengan satu API key kamu bisa memanggil Claude, GPT, DeepSeek, Kimi, GLM, Qwen, Gemini, dan model lain. Saldo dalam Rupiah, top up lewat QRIS mulai Rp10.000.

Vikey memakai format API yang sama dengan OpenAI dan Anthropic. Kode, SDK, dan coding agent yang sudah kamu pakai cukup diganti dua hal: **base URL** dan **API key**.

## Yang perlu kamu tahu dulu

[Section titled “Yang perlu kamu tahu dulu”](#yang-perlu-kamu-tahu-dulu)

| Hal                       | Nilai                                                                               |
| ------------------------- | ----------------------------------------------------------------------------------- |
| Base URL format OpenAI    | `https://api.vikey.ai/v1`                                                           |
| Base URL format Anthropic | `https://api.vikey.ai`                                                              |
| Header autentikasi        | `Authorization: Bearer API_KEY` atau `x-api-key: API_KEY`                           |
| Bentuk model id           | `provider/nama`, misalnya `anthropic/claude-sonnet-5.5`                             |
| Daftar model              | `GET https://api.vikey.ai/v1/models` atau [halaman harga](https://vikey.ai/pricing) |

## Mulai dari mana

[Section titled “Mulai dari mana”](#mulai-dari-mana)

[Quickstart](/quickstart/)Daftar, top up, buat API key, dan kirim request pertama.

[Claude Code](/agents/claude-code/)Pakai Vikey di Claude Code, termasuk setelan model.

[Codex CLI](/agents/codex/)Tambahkan Vikey sebagai model provider di config.toml.

[opencode](/agents/opencode/)Provider Vikey di opencode.jsonc, sudah diuji di versi terbaru.

[Vikey Auto](/models/vikey-auto/)Satu model id, Vikey memilih model ringan, sedang, atau berat per tugas.

[Setup lewat AI agent](/setup-with-ai/)Minta agent kamu membaca docs ini dan mengatur dirinya sendiri.

## Untuk AI agent

[Section titled “Untuk AI agent”](#untuk-ai-agent)

Setiap halaman docs ini juga tersedia sebagai Markdown biasa. Tambahkan `.md` di akhir URL, misalnya `https://docs.vikey.ai/agents/claude-code.md`. Ringkasan seluruh docs ada di [`/llms.txt`](/llms.txt) dan isi lengkapnya di [`/llms-full.txt`](/llms-full.txt).

# API key

> Membuat, membatasi, menonaktifkan, dan menyimpan API key Vikey dengan aman.

API key adalah kunci yang dipakai aplikasi dan coding agent untuk memanggil Vikey. Semua key milik satu akun memakai saldo yang sama.

## Membuat key

[Section titled “Membuat key”](#membuat-key)

Buka menu **API Keys** di dashboard, lalu buat key baru. Beri nama yang jelas, misalnya `laptop-kantor` atau `bot-telegram`, supaya pemakaiannya mudah dibedakan.

Buat key terpisah untuk tiap mesin atau aplikasi. Kalau satu key bocor, kamu cukup menonaktifkan key itu tanpa mengganggu yang lain.

## Setelan per key

[Section titled “Setelan per key”](#setelan-per-key)

| Setelan                   | Fungsi                                                                                                                                       |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Batas pemakaian           | Opsional. Membatasi jumlah request untuk key ini.                                                                                            |
| Aktif atau nonaktif       | Key yang dinonaktifkan langsung ditolak dengan `403`, tanpa perlu dihapus. Bisa diaktifkan lagi kapan saja.                                  |
| Sembunyikan nama provider | `GET /v1/models` menampilkan nama pendek seperti `claude-sonnet-5.5`. Lihat [Memilih model](/models/choosing/#menyembunyikan-nama-provider). |

## Menyimpan key dengan aman

[Section titled “Menyimpan key dengan aman”](#menyimpan-key-dengan-aman)

* Simpan key di variabel environment, misalnya `VIKEY_API_KEY`, bukan di kode.
* Jangan commit key ke repository. Untuk Claude Code, pakai `~/.claude/settings.json` atau `.claude/settings.local.json`, bukan `.claude/settings.json` milik proyek.
* Jangan taruh key di aplikasi frontend atau aplikasi mobile. Panggil Vikey dari server kamu.

Key bocor?

Nonaktifkan key itu di menu **API Keys**, buat key baru, lalu ganti di semua tempat yang memakainya. Cek menu **Usage** untuk melihat pemakaian yang tidak kamu kenali.

# Organisasi dan tim

> Saldo bersama, workspace, anggota, dan API key milik organisasi di Vikey.

Organisasi dipakai untuk berbagi saldo dengan tim dan memisahkan project dengan workspace.

## Yang ada di organisasi

[Section titled “Yang ada di organisasi”](#yang-ada-di-organisasi)

| Bagian             | Fungsi                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Saldo organisasi   | Satu saldo yang dipakai semua API key organisasi. Top up dari menu **Billing** saat organisasi sedang dipilih.                                          |
| Workspace          | Pemisah project di dalam organisasi. Personal workspace dibuat otomatis saat organisasi dibuat.                                                         |
| Anggota            | Diundang lewat email. Peran yang tersedia: owner, admin, member, dan viewer. Akses anggota bisa dibatasi ke workspace tertentu atau ke semua workspace. |
| API key organisasi | Dibuat di dalam workspace dan memotong saldo organisasi. Key hanya ditampilkan sekali saat dibuat, jadi langsung simpan di tempat aman.                 |

## Berpindah antara akun pribadi dan organisasi

[Section titled “Berpindah antara akun pribadi dan organisasi”](#berpindah-antara-akun-pribadi-dan-organisasi)

Pemilih di dashboard menentukan kamu sedang melihat akun pribadi atau organisasi mana. Saldo, pemakaian, dan API key yang tampil mengikuti pilihan itu.

## Membuat organisasi

[Section titled “Membuat organisasi”](#membuat-organisasi)

Buat organisasi dari dashboard, undang anggota, lalu isi saldo organisasi. Pengaturan anggota, workspace, dan key ada di menu **Organization Settings**.

Untuk menghapus organisasi, cabut dulu semua API key yang masih aktif.

# Affiliate

> Link referral, cara komisi dihitung dari top up, dan saldo komisi di Vikey.

Setiap akun Vikey otomatis punya kode referral. Ajak orang memakai Vikey, dan kamu dapat komisi dari top up mereka.

## Link referral

[Section titled “Link referral”](#link-referral)

Link referral berbentuk:

```text
https://vikey.ai/?ref=kode-kamu
```

Kode bawaan berisi 8 karakter. Kamu bisa menggantinya di menu **Affiliate** dengan kode sendiri: 3 sampai 20 karakter, berisi huruf, angka, `-`, atau `_`, dan belum dipakai orang lain. Huruf besar dan kecil dianggap sama.

Orang yang datang lewat link itu otomatis terisi kode referral-nya saat mendaftar. Kode juga bisa diketik manual di formulir daftar. Kode yang tidak valid ditolak dengan pesan yang jelas, bukan diabaikan diam-diam.

## Cara komisi dihitung

[Section titled “Cara komisi dihitung”](#cara-komisi-dihitung)

* Komisi dihitung dari **top up**, bukan dari pemakaian API.
* Begitu orang yang kamu ajak menyelesaikan top up, persentase dari nilai top up itu masuk ke saldo komisimu.
* Rate yang berlaku saat ini, termasuk promo untuk top up pertama kalau sedang ada, selalu ditampilkan di menu **Affiliate**.

## Saldo komisi

[Section titled “Saldo komisi”](#saldo-komisi)

Saldo komisi terpisah dari saldo pemakaian. Riwayat komisi dan pencairannya bisa dilihat di menu **Affiliate**.

# Top up dan saldo

> Top up saldo Vikey lewat QRIS mulai Rp10.000, konfirmasi otomatis, dan cara saldo terpotong.

Saldo Vikey dalam Rupiah. Saldo terpotong otomatis setiap request selesai, sesuai biaya yang tercatat di menu **Usage**.

## Top up lewat QRIS

[Section titled “Top up lewat QRIS”](#top-up-lewat-qris)

1. Buka menu **Billing** di dashboard, lalu **Top up**.
2. Isi nominal. Minimal Rp10.000. Batas maksimal per top up ditampilkan di formulir.
3. Pindai kode QRIS dengan e-wallet atau aplikasi mobile banking apa pun.
4. Saldo masuk otomatis setelah pembayaran terkonfirmasi, biasanya dalam hitungan detik. Halaman tidak perlu di-refresh.

Top up yang belum dibayar bisa dibatalkan dari halaman detailnya. QRIS saat ini satu-satunya metode pembayaran.

## Saldo organisasi

[Section titled “Saldo organisasi”](#saldo-organisasi)

Kalau kamu bekerja di dalam [organisasi](/account/organizations/), request dari API key milik organisasi memotong saldo organisasi, bukan saldo pribadimu. Top up saldo organisasi dilakukan dari menu **Billing** saat organisasi itu sedang dipilih.

## Saat saldo habis

[Section titled “Saat saldo habis”](#saat-saldo-habis)

Request yang perkiraan biayanya lebih besar dari saldo ditolak dengan status `402` dan tidak ditagih. Coding agent biasanya menampilkan pesan ini sebagai error API. Top up, lalu lanjutkan sesi.

# Claude Code

> Pakai Vikey di Claude Code lewat settings.json, termasuk pemetaan model Claude, Vikey Auto, dan model untuk tugas latar belakang.

Claude Code bicara dengan format Anthropic (`/v1/messages`). Vikey menerima format itu, jadi kamu cukup mengarahkan Claude Code ke Vikey dan memberi tahu model id mana yang dipakai.

Diuji dengan Claude Code 2.1.323 pada 13 November 2026.

## Config yang disarankan

[Section titled “Config yang disarankan”](#config-yang-disarankan)

Tulis ini ke `~/.claude/settings.json` (Windows: `%USERPROFILE%\.claude\settings.json`). Kalau file itu sudah ada, gabungkan isinya, jangan ditimpa.

\~/.claude/settings.json

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.vikey.ai",
    "ANTHROPIC_AUTH_TOKEN": "API_KEY_KAMU",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "modelOverrides": {
    "claude-opus-5-5": "anthropic/claude-opus-5.5",
    "claude-sonnet-5-5": "anthropic/claude-sonnet-5.5",
    "claude-haiku-5-5": "anthropic/haiku-5.5"
  }
}
```

Lalu jalankan `claude` seperti biasa. `/model sonnet`, `/model opus`, dan `/model haiku` sekarang memakai model Claude di Vikey.

### Kenapa tiap baris ada

[Section titled “Kenapa tiap baris ada”](#kenapa-tiap-baris-ada)

| Baris                                        | Fungsi                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL`                         | Mengarahkan semua request ke Vikey. Tanpa `/v1`, karena Claude Code menambahkan `/v1/messages` sendiri.                                                                                                                                                                                                          |
| `ANTHROPIC_AUTH_TOKEN`                       | API key Vikey, dikirim sebagai `Authorization: Bearer`. Variabel ini langsung dipakai tanpa konfirmasi dan menang atas login claude.ai.                                                                                                                                                                          |
| `CLAUDE_CODE_ATTRIBUTION_HEADER`             | `0` menghapus blok atribusi yang berubah-ubah dari system prompt, supaya bagian prompt yang sama bisa ditagih dengan harga cache.                                                                                                                                                                                |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1` membuat `/model` menampilkan model dari `GET /v1/models` Vikey, jadi kamu bisa memilih model lain dari daftar.                                                                                                                                                                                               |
| `modelOverrides`                             | Nama model bawaan Claude Code (`claude-sonnet-5-5`) tidak sama dengan model id Vikey (`anthropic/claude-sonnet-5.5`). Pemetaan ini membuat alias `opus`, `sonnet`, `haiku`, dan tugas latar belakang (judul sesi, ringkasan) memakai model Vikey yang benar, dan Claude Code tetap mengenali kemampuan modelnya. |

Jangan taruh key di repository

Simpan config ini di `~/.claude/settings.json` (berlaku untuk semua proyek) atau `.claude/settings.local.json` (satu proyek, tidak ter-commit). Jangan tulis key di `.claude/settings.json` milik proyek, karena file itu ikut ter-commit.

## Pakai Vikey Auto atau model non Claude

[Section titled “Pakai Vikey Auto atau model non Claude”](#pakai-vikey-auto-atau-model-non-claude)

Claude Code juga bisa memakai model selain Claude, misalnya GPT atau DeepSeek, karena Vikey yang menerjemahkan formatnya. Tambahkan `model` di settings.json:

\~/.claude/settings.json

```diff
{
  +"model": "vikey/agent-coding",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.vikey.ai",
    "ANTHROPIC_AUTH_TOKEN": "API_KEY_KAMU",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "modelOverrides": {
    "claude-opus-5-5": "anthropic/claude-opus-5.5",
    "claude-sonnet-5-5": "anthropic/claude-sonnet-5.5",
    "claude-haiku-5-5": "anthropic/haiku-5.5"
  }
}
```

Atau untuk satu sesi saja: `claude --model vikey/agent-gpt`.

Pilihan model id yang umum dipakai:

| Model id                                                          | Isinya                                                                         |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `vikey/agent-coding`                                              | Vikey Auto dengan model Claude: Haiku 5.5, Sonnet 5.5, Opus 5.5                |
| `vikey/agent-gpt`                                                 | Vikey Auto dengan model GPT: GPT-6 Luna, GPT-5.6 Terra, GPT-6.1 Sol            |
| `vikey/agent-mocin`                                               | Vikey Auto paling hemat, model DeepSeek V4.1 Flash                             |
| `openai/gpt-6.1-sol`, `deepseek/deepseek-v4.1-flash`, dan lainnya | Satu model tetap. Daftar lengkap di [halaman harga](https://vikey.ai/pricing). |

Saat memakai model id yang tidak dikenal Claude Code, muncul pesan `Claude Code doesn't recognize the model ...`. Itu hanya peringatan: Claude Code menganggap context window 1 juta token, sama dengan yang tercatat di Vikey untuk model-model ini. Kalau mau batas lain, set `CLAUDE_CODE_MAX_CONTEXT_TOKENS`, misalnya `"CLAUDE_CODE_MAX_CONTEXT_TOKENS": "200000"` di blok `env`.

Cara kerja Vikey Auto dan biayanya dijelaskan di [Vikey Auto](/models/vikey-auto/).

## Coba dulu tanpa mengubah file

[Section titled “Coba dulu tanpa mengubah file”](#coba-dulu-tanpa-mengubah-file)

Untuk mencoba di satu terminal saja:

* macOS / Linux

  ```bash
  export ANTHROPIC_BASE_URL=https://api.vikey.ai
  export ANTHROPIC_AUTH_TOKEN=API_KEY_KAMU
  export ANTHROPIC_DEFAULT_HAIKU_MODEL=openai/gpt-6-luna
  claude --model vikey/agent-coding
  ```

* PowerShell

  ```powershell
  $env:ANTHROPIC_BASE_URL = "https://api.vikey.ai"
  $env:ANTHROPIC_AUTH_TOKEN = "API_KEY_KAMU"
  $env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "openai/gpt-6-luna"
  claude --model vikey/agent-coding
  ```

`ANTHROPIC_DEFAULT_HAIKU_MODEL` menggantikan `modelOverrides` untuk tugas latar belakang. Tanpa salah satunya, Claude Code mengirim nama model bawaannya untuk judul sesi dan ringkasan, lalu request itu gagal dengan `Model not found`.

## Cek koneksi

[Section titled “Cek koneksi”](#cek-koneksi)

1. Tes key dan base URL langsung, tanpa Claude Code:

   ```bash
   curl -sS https://api.vikey.ai/v1/messages \
     -H "Authorization: Bearer API_KEY_KAMU" \
     -H "anthropic-version: 2023-06-01" \
     -H "content-type: application/json" \
     -d '{"model": "openai/gpt-6-luna", "max_tokens": 32, "messages": [{"role": "user", "content": "ping"}]}'
   ```

   Response yang berisi `"content"` berarti key dan base URL sudah benar.

2. Jalankan `claude`, kirim satu pesan, lalu ketik `/status`. Baris **Anthropic base URL** harus menunjukkan `https://api.vikey.ai`, dan baris **Auth token** harus menyebut `ANTHROPIC_AUTH_TOKEN`.

## VS Code

[Section titled “VS Code”](#vs-code)

Ekstensi Claude Code di VS Code membaca variabel dari setelan VS Code sendiri. Buka **Preferences: Open User Settings (JSON)** lalu tambahkan:

```json
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.vikey.ai" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "API_KEY_KAMU" }
  ]
}
```

`modelOverrides` tetap dibaca dari `~/.claude/settings.json`.

## Masalah umum

[Section titled “Masalah umum”](#masalah-umum)

| Yang kamu lihat                                               | Penyebab                                                  | Solusi                                                                                                   |
| ------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `Model 'claude-...' not found`                                | Claude Code mengirim nama model bawaannya                 | Pasang `modelOverrides` seperti di atas, atau set `ANTHROPIC_DEFAULT_HAIKU_MODEL`                        |
| Diminta login padahal curl berhasil                           | Key belum terbaca sebelum layar login muncul              | Taruh `ANTHROPIC_AUTH_TOKEN` di `~/.claude/settings.json` atau export di shell, bukan di settings proyek |
| Peringatan dua sumber login (`auth may not work as expected`) | Key Vikey dan login claude.ai aktif bersamaan             | Jalankan `/logout` supaya hanya key Vikey yang dipakai                                                   |
| `ANTHROPIC_API_KEY` diabaikan                                 | Variabel ini perlu disetujui sekali di mode interaktif    | Pakai `ANTHROPIC_AUTH_TOKEN`, atau setujui lewat `/config`                                               |
| `400` dengan `Extra inputs are not permitted`                 | Fitur beta Claude Code yang belum diteruskan model tujuan | Tambahkan `"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"` di blok `env`                                  |
| `402 Insufficient balance`                                    | Saldo habis                                               | [Top up](/account/top-up/), lalu lanjutkan sesi                                                          |

# Cline, Roo Code, Kilo Code

> Pakai Vikey di ekstensi VS Code Cline, Roo Code, dan Kilo Code lewat provider OpenAI Compatible.

Ketiga ekstensi ini punya provider **OpenAI Compatible** dengan isian yang sama. Letak menunya bisa sedikit berbeda antar versi, tapi isiannya tetap empat ini.

## Langkah

[Section titled “Langkah”](#langkah)

1. Buka panel ekstensi di VS Code, lalu buka **Settings** (ikon roda gigi) di panel itu.

2. Di **API Provider**, pilih **OpenAI Compatible**.

3. Isi:

   | Isian    | Nilai                                                                                             |
   | -------- | ------------------------------------------------------------------------------------------------- |
   | Base URL | `https://api.vikey.ai/v1`                                                                         |
   | API Key  | API key Vikey kamu                                                                                |
   | Model ID | Misalnya `vikey/agent-coding`, `anthropic/claude-sonnet-5.5`, atau `deepseek/deepseek-v4.1-flash` |

4. Simpan, lalu kirim satu pesan pendek untuk mengecek.

## Setelan model (opsional)

[Section titled “Setelan model (opsional)”](#setelan-model-opsional)

Beberapa versi menampilkan bagian **Model Configuration**. Isi sesuai model yang kamu pakai:

| Isian                  | Saran                                                                                                                         |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Context window         | `1000000` untuk model Claude, GPT, dan DeepSeek di Vikey. Lihat angka per model di [halaman harga](https://vikey.ai/pricing). |
| Supports images        | Aktifkan kalau model punya kemampuan vision                                                                                   |
| Harga input dan output | Boleh dikosongkan. Biaya yang benar selalu ada di menu **Usage** dashboard Vikey.                                             |

Tips

Ekstensi ini mengirim ulang seluruh riwayat dan hasil tool di setiap langkah. [Vikey Auto](/models/vikey-auto/) memangkas hasil tool lama yang sudah tidak relevan, jadi biaya sesi panjang di ekstensi ini bisa turun cukup banyak.

## Masalah umum

[Section titled “Masalah umum”](#masalah-umum)

| Yang kamu lihat            | Penyebab                                           | Solusi                                                  |
| -------------------------- | -------------------------------------------------- | ------------------------------------------------------- |
| `404`                      | Base URL tanpa `/v1`, atau `/v1` tertulis dua kali | Isi persis `https://api.vikey.ai/v1`                    |
| `Model '...' not found`    | Model ID salah ketik                               | Salin id dari [halaman harga](https://vikey.ai/pricing) |
| `402 Insufficient balance` | Saldo habis                                        | [Top up](/account/top-up/)                              |

# Codex CLI dan Codex Desktop

> Tambahkan Vikey sebagai model provider di ~/.codex/config.toml dengan wire_api responses.

Codex memakai format OpenAI Responses (`/v1/responses`). Vikey mendukung format itu untuk semua model teks, termasuk model Claude dan DeepSeek.

Diuji dengan Codex CLI 0.167 pada 13 November 2026.

## Config yang disarankan

[Section titled “Config yang disarankan”](#config-yang-disarankan)

1. Simpan API key di variabel environment. Tambahkan baris ini ke `~/.zshrc` atau `~/.bashrc` supaya tetap ada di terminal baru:

   ```bash
   export VIKEY_API_KEY=API_KEY_KAMU
   ```

2. Tulis provider Vikey di `~/.codex/config.toml`:

   \~/.codex/config.toml

   ```toml
   model = "vikey/agent-gpt"
   model_provider = "vikey"


   [model_providers.vikey]
   name = "Vikey"
   base_url = "https://api.vikey.ai/v1"
   env_key = "VIKEY_API_KEY"
   wire_api = "responses"
   ```

3. Jalankan `codex`. Ganti model untuk satu sesi dengan `codex -m openai/gpt-6.1-sol`.

### Kenapa tiap baris ada

[Section titled “Kenapa tiap baris ada”](#kenapa-tiap-baris-ada)

| Baris                    | Fungsi                                                                                                                                                         |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                  | Model default. Bisa model tetap seperti `openai/gpt-6.1-sol` atau [Vikey Auto](/models/vikey-auto/) seperti `vikey/agent-gpt`.                                 |
| `model_provider`         | Memilih provider `vikey` yang didefinisikan di bawahnya. Nama `openai`, `ollama`, dan `lmstudio` sudah dipakai Codex, jadi jangan dipakai sebagai id provider. |
| `base_url`               | Dengan `/v1`. Codex menambahkan `/responses` sendiri.                                                                                                          |
| `env_key`                | Nama variabel environment yang berisi API key. Key tidak ditulis di file.                                                                                      |
| `wire_api = "responses"` | Wajib `"responses"`. Codex versi sekarang menolak `"chat"` dengan pesan `wire_api = "chat" is no longer supported`.                                            |

Perhatian

Config provider hanya dibaca dari `~/.codex/config.toml`. Codex mengabaikan setelan provider di `.codex/config.toml` milik proyek.

## Codex Desktop (macOS)

[Section titled “Codex Desktop (macOS)”](#codex-desktop-macos)

Codex Desktop memakai file `~/.codex/config.toml` yang sama. Bedanya, aplikasi yang dibuka dari Dock tidak membaca variabel yang di-export di terminal. Daftarkan key di level sistem, lalu tutup penuh dan buka lagi Codex Desktop:

```bash
launchctl setenv VIKEY_API_KEY API_KEY_KAMU
```

`launchctl setenv` hilang setelah restart Mac. Jalankan lagi setelah restart, atau buka Codex Desktop dari terminal yang sudah punya `VIKEY_API_KEY`.

## Beberapa setelan sekaligus (profile)

[Section titled “Beberapa setelan sekaligus (profile)”](#beberapa-setelan-sekaligus-profile)

Sejak Codex 0.134, profile ditulis sebagai file terpisah. Contoh profile hemat di `~/.codex/hemat.config.toml`:

\~/.codex/hemat.config.toml

```toml
model = "vikey/agent-mocin"
model_provider = "vikey"
```

Jalankan dengan `codex --profile hemat`. Provider `vikey` tetap diambil dari `~/.codex/config.toml`.

## Cek koneksi

[Section titled “Cek koneksi”](#cek-koneksi)

```bash
curl -sS https://api.vikey.ai/v1/responses \
  -H "Authorization: Bearer $VIKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-6-luna", "input": "ping"}'
```

Response yang berisi `"output"` berarti key dan base URL sudah benar. Setelah itu coba `codex exec "balas dengan kata ok"`.

## Masalah umum

[Section titled “Masalah umum”](#masalah-umum)

| Yang kamu lihat                                         | Penyebab                                                                      | Solusi                                                                        |
| ------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `401` atau `Missing environment variable VIKEY_API_KEY` | Variabel belum di-export di terminal ini, atau Codex Desktop tidak melihatnya | `export VIKEY_API_KEY=...`, atau `launchctl setenv` untuk Codex Desktop       |
| `404` di `/v1/v1/responses`                             | `/v1` tertulis dua kali                                                       | `base_url` cukup `https://api.vikey.ai/v1`                                    |
| `wire_api = "chat" is no longer supported`              | Masih memakai config lama                                                     | Ganti jadi `wire_api = "responses"`                                           |
| `Model '...' not found`                                 | Model id salah ketik                                                          | Ambil id dari `GET /v1/models` atau [halaman harga](https://vikey.ai/pricing) |

# Hermes

> Daftarkan Vikey sebagai provider di ~/.hermes/config.yaml untuk Hermes Agent.

Hermes Agent memanggil Vikey lewat format OpenAI chat completions.

Diuji dengan Hermes Agent 0.21.2 pada 12 November 2026.

## Langkah

[Section titled “Langkah”](#langkah)

1. Pasang Hermes kalau belum ada:

   ```bash
   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
   ```

2. Simpan API key di variabel environment:

   ```bash
   export VIKEY_API_KEY=API_KEY_KAMU
   ```

3. Tambahkan provider Vikey dan jadikan model default di `~/.hermes/config.yaml`:

   \~/.hermes/config.yaml

   ```yaml
   model:
     default: vikey/agent-gpt
     provider: vikey
     base_url: https://api.vikey.ai/v1
     key_env: VIKEY_API_KEY
     api_mode: chat_completions


   providers:
     vikey:
       name: Vikey
       base_url: https://api.vikey.ai/v1
       key_env: VIKEY_API_KEY
       model: vikey/agent-gpt
       models:
         vikey/agent-gpt: {}
         openai/gpt-6.1-sol: {}
         deepseek/deepseek-v4.1-flash: {}
   ```

4. Jalankan `hermes`. Untuk ganti model, jalankan `hermes model`, pilih **Vikey**, lalu pilih modelnya.

Cara lain tanpa menyunting file:

```bash
hermes config set providers.vikey.name "Vikey"
hermes config set providers.vikey.base_url "https://api.vikey.ai/v1"
hermes config set providers.vikey.key_env "VIKEY_API_KEY"
hermes model
```

## Masalah umum

[Section titled “Masalah umum”](#masalah-umum)

| Yang kamu lihat                                           | Penyebab                                                                         | Solusi                                                                                                                                         |
| --------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `Connection error` atau timeout di Hermes Desktop (macOS) | Masalah TLS di HTTP client bawaan Hermes Desktop, bukan di config atau API Vikey | Untuk sementara ganti `base_url` ke `http://api.vikey.ai/v1`, restart Hermes Desktop, lalu kembalikan ke `https` setelah Hermes memperbaikinya |
| `401`                                                     | `VIKEY_API_KEY` tidak terbaca                                                    | Export ulang, lalu jalankan Hermes dari terminal yang sama                                                                                     |
| `Model '...' not found`                                   | Model id salah ketik                                                             | Salin id dari [halaman harga](https://vikey.ai/pricing)                                                                                        |

Perhatian

Pakai `http://` hanya sebagai solusi sementara untuk masalah TLS di atas. Request lewat `http` tidak terenkripsi.

# OpenClaw

> Daftarkan Vikey sebagai custom provider di OpenClaw lewat openclaw onboard.

OpenClaw mendaftarkan provider lewat perintah `openclaw onboard`. Vikey didaftarkan sebagai **custom provider** dengan API key.

## Langkah

[Section titled “Langkah”](#langkah)

1. Pasang atau perbarui OpenClaw:

   ```bash
   npm install -g openclaw@latest
   ```

2. Daftarkan Vikey. Ganti `API_KEY_KAMU` dan model sesuai kebutuhan:

   ```bash
   openclaw onboard --non-interactive --accept-risk \
     --auth-choice custom-api-key \
     --custom-provider-id vikey \
     --custom-base-url "https://api.vikey.ai/v1" \
     --custom-model-id "vikey/agent-gpt" \
     --custom-api-key "API_KEY_KAMU" \
     --custom-compatibility openai-responses \
     --gateway-port 18789 \
     --skip-health
   ```

3. Jalankan gateway OpenClaw dan pilih modelnya:

   ```bash
   openclaw gateway --port 18789 --verbose
   openclaw models set vikey/vikey/agent-gpt
   ```

### Arti tiap flag

[Section titled “Arti tiap flag”](#arti-tiap-flag)

| Flag                         | Fungsi                                                                                        |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| `--custom-provider-id vikey` | Nama provider di OpenClaw. Model dipanggil sebagai `vikey/<model-id>`.                        |
| `--custom-base-url`          | Dengan `/v1`.                                                                                 |
| `--custom-model-id`          | Model id Vikey, misalnya `vikey/agent-gpt` atau `anthropic/claude-sonnet-5.5`.                |
| `--custom-api-key`           | API key Vikey. Kalau flag ini tidak diisi, OpenClaw membaca variabel `CUSTOM_API_KEY`.        |
| `--custom-compatibility`     | Format API. Vikey mendukung `openai-responses`, `openai` (chat completions), dan `anthropic`. |

Cek versi OpenClaw kamu

Pilihan `openai-responses` baru ada di OpenClaw versi 2026.6 ke atas. Versi lebih lama hanya mengenal `openai` dan `anthropic`, jadi pakai `--custom-compatibility openai` kalau perintah di atas ditolak. Jalankan `openclaw onboard --help` untuk melihat flag yang didukung versimu.

## Masalah umum

[Section titled “Masalah umum”](#masalah-umum)

| Yang kamu lihat                       | Penyebab             | Solusi                                                  |
| ------------------------------------- | -------------------- | ------------------------------------------------------- |
| Flag `--custom-compatibility` ditolak | Versi OpenClaw lama  | Perbarui OpenClaw, atau pakai nilai `openai`            |
| `401`                                 | API key salah        | Ulangi langkah 2 dengan key yang benar                  |
| `Model '...' not found`               | Model id salah ketik | Salin id dari [halaman harga](https://vikey.ai/pricing) |

# opencode

> Provider Vikey di opencode.jsonc dengan @ai-sdk/openai-compatible, termasuk small_model untuk judul sesi.

opencode memanggil Vikey lewat format OpenAI chat completions.

Diuji dengan opencode 1.19.5 (versi terbaru) pada 13 November 2026.

## Config yang disarankan

[Section titled “Config yang disarankan”](#config-yang-disarankan)

1. Simpan API key di variabel environment:

   ```bash
   export VIKEY_API_KEY=API_KEY_KAMU
   ```

2. Tulis provider Vikey di `~/.config/opencode/opencode.jsonc` (berlaku untuk semua proyek) atau `opencode.jsonc` di folder proyek:

   \~/.config/opencode/opencode.jsonc

   ```jsonc
   {
     "$schema": "https://opencode.ai/config.json",
     "provider": {
       "vikey": {
         "npm": "@ai-sdk/openai-compatible",
         "name": "Vikey",
         "options": {
           "baseURL": "https://api.vikey.ai/v1",
           "apiKey": "{env:VIKEY_API_KEY}"
         },
         "models": {
           "vikey/agent-gpt": { "name": "Vikey Auto GPT" },
           "vikey/agent-coding": { "name": "Vikey Auto Claude" },
           "anthropic/claude-sonnet-5.5": { "name": "Claude Sonnet 5.5" },
           "openai/gpt-6.1-sol": { "name": "GPT-6.1 Sol" },
           "openai/gpt-6-luna": { "name": "GPT-6 Luna" }
         }
       }
     },
     "model": "vikey/vikey/agent-gpt",
     "small_model": "vikey/openai/gpt-6-luna"
   }
   ```

3. Jalankan `opencode`. Ganti model dengan perintah `/models`.

### Kenapa tiap baris ada

[Section titled “Kenapa tiap baris ada”](#kenapa-tiap-baris-ada)

| Baris             | Fungsi                                                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm`             | Paket penghubung untuk API yang kompatibel OpenAI. opencode mengunduhnya otomatis saat pertama dipakai.                                                                   |
| `options.baseURL` | Dengan `/v1`.                                                                                                                                                             |
| `options.apiKey`  | `{env:VIKEY_API_KEY}` membaca key dari variabel environment, jadi key tidak tertulis di file.                                                                             |
| `models`          | Model yang muncul di `/models`. Kunci di dalamnya harus sama persis dengan model id Vikey.                                                                                |
| `model`           | Model default, ditulis `id-provider/model-id`. Karena model id Vikey juga memakai garis miring, hasilnya seperti `vikey/vikey/agent-gpt` atau `vikey/openai/gpt-6.1-sol`. |
| `small_model`     | Model untuk tugas kecil seperti membuat judul sesi. Pilih model murah supaya tugas ini hampir tidak memakan biaya.                                                        |

Format providers di situs opencode

Situs opencode sudah menampilkan format baru `providers` dengan `package` dan `settings`. opencode 1.19.5 mengabaikan format itu dengan pesan `cannot be represented in V1`, lalu gagal dengan `Model not found`. Pakai format `provider` seperti di atas sampai rilis opencode mendukung format baru.

## Cara lain memasukkan key

[Section titled “Cara lain memasukkan key”](#cara-lain-memasukkan-key)

Kalau tidak mau memakai variabel environment, hapus baris `apiKey` dari config, jalankan `opencode`, ketik `/connect`, pilih **Vikey**, lalu tempel API key. opencode menyimpan key itu di penyimpanan kredensialnya sendiri.

## Cek koneksi

[Section titled “Cek koneksi”](#cek-koneksi)

```bash
opencode run "balas dengan kata ok"
```

Kalau berhasil, opencode menampilkan `ok` beserta nama model yang dipakai.

## Masalah umum

[Section titled “Masalah umum”](#masalah-umum)

| Yang kamu lihat                | Penyebab                                                                 | Solusi                                                                 |
| ------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `Model not found: vikey/...`   | Model belum ada di `models`, atau format `providers` yang belum didukung | Tambahkan model id ke `models`, pakai format `provider`                |
| `401`                          | `VIKEY_API_KEY` belum di-export di terminal ini                          | Export ulang, atau pakai `/connect`                                    |
| Judul sesi memakai model mahal | `small_model` belum diisi                                                | Isi `small_model` dengan model murah seperti `vikey/openai/gpt-6-luna` |

# SDK dan tool lain

> Pakai Vikey dari SDK OpenAI, SDK Anthropic, dan tool apa pun yang bisa diatur base URL-nya.

Tool apa pun yang bisa diatur **base URL** dan **API key** untuk OpenAI atau Anthropic bisa memakai Vikey. Aturannya:

| Tool memakai format | Base URL                  | Contoh model                                        |
| ------------------- | ------------------------- | --------------------------------------------------- |
| OpenAI              | `https://api.vikey.ai/v1` | `openai/gpt-6.1-sol`, `vikey/agent-gpt`             |
| Anthropic           | `https://api.vikey.ai`    | `anthropic/claude-sonnet-5.5`, `vikey/agent-coding` |

Model dari provider mana pun bisa dipanggil lewat kedua format. Misalnya model GPT bisa dipanggil lewat SDK Anthropic, dan model Claude lewat SDK OpenAI.

## SDK OpenAI

[Section titled “SDK OpenAI”](#sdk-openai)

* Python

  ```python
  from openai import OpenAI


  client = OpenAI(base_url="https://api.vikey.ai/v1", api_key="API_KEY_KAMU")


  stream = client.chat.completions.create(
      model="anthropic/claude-sonnet-5.5",
      messages=[{"role": "user", "content": "Jelaskan rekursi dalam dua kalimat."}],
      stream=True,
  )
  for chunk in stream:
      print(chunk.choices[0].delta.content or "", end="")
  ```

* Node.js

  ```js
  import OpenAI from 'openai'


  const client = new OpenAI({ baseURL: 'https://api.vikey.ai/v1', apiKey: 'API_KEY_KAMU' })


  const stream = await client.chat.completions.create({
    model: 'anthropic/claude-sonnet-5.5',
    messages: [{ role: 'user', content: 'Jelaskan rekursi dalam dua kalimat.' }],
    stream: true,
  })
  for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content || '')
  ```

## SDK Anthropic

[Section titled “SDK Anthropic”](#sdk-anthropic)

* Python

  ```python
  import anthropic


  client = anthropic.Anthropic(base_url="https://api.vikey.ai", api_key="API_KEY_KAMU")


  message = client.messages.create(
      model="anthropic/claude-sonnet-5.5",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Jelaskan rekursi dalam dua kalimat."}],
  )
  print(message.content[0].text)
  ```

* Node.js

  ```js
  import Anthropic from '@anthropic-ai/sdk'


  const client = new Anthropic({ baseURL: 'https://api.vikey.ai', apiKey: 'API_KEY_KAMU' })


  const message = await client.messages.create({
    model: 'anthropic/claude-sonnet-5.5',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Jelaskan rekursi dalam dua kalimat.' }],
  })
  console.log(message.content[0].text)
  ```

## Lewat variabel environment

[Section titled “Lewat variabel environment”](#lewat-variabel-environment)

Banyak tool membaca variabel standar ini. Kalau tool kamu mendukungnya, cukup set:

```bash
# Tool format OpenAI
export OPENAI_BASE_URL=https://api.vikey.ai/v1
export OPENAI_API_KEY=API_KEY_KAMU


# Tool format Anthropic
export ANTHROPIC_BASE_URL=https://api.vikey.ai
export ANTHROPIC_AUTH_TOKEN=API_KEY_KAMU
```

Lalu pilih model id Vikey di setelan tool tersebut.

# Chat Completions

> POST /v1/chat/completions, format OpenAI, untuk semua model teks di Vikey termasuk Claude dan Vikey Auto.

```http
POST https://api.vikey.ai/v1/chat/completions
```

Format request dan response sama dengan [Chat Completions OpenAI](https://platform.openai.com/docs/api-reference/chat). Endpoint ini melayani semua model teks di Vikey, bukan hanya model OpenAI.

## Contoh

[Section titled “Contoh”](#contoh)

```bash
curl https://api.vikey.ai/v1/chat/completions \
  -H "Authorization: Bearer API_KEY_KAMU" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "max_tokens": 1024,
    "messages": [
      {"role": "system", "content": "Jawab singkat dalam bahasa Indonesia."},
      {"role": "user", "content": "Apa beda let dan const di JavaScript?"}
    ]
  }'
```

## Parameter yang sering dipakai

[Section titled “Parameter yang sering dipakai”](#parameter-yang-sering-dipakai)

| Parameter                      | Keterangan                                                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `model`                        | Wajib. Model id, misalnya `openai/gpt-6.1-sol` atau `vikey/agent-gpt`.                                                          |
| `messages`                     | Wajib. Array pesan dengan `role` (`system`, `user`, `assistant`, `tool`) dan `content`.                                         |
| `max_tokens`                   | Batas token output. Juga dipakai untuk [pengecekan saldo](/models/pricing/#pengecekan-saldo), jadi isi dengan angka yang wajar. |
| `stream`                       | `true` untuk Server-Sent Events. Stream diakhiri `data: [DONE]`.                                                                |
| `tools`, `tool_choice`         | Function calling dengan format OpenAI.                                                                                          |
| `temperature`, `top_p`, `stop` | Diteruskan ke model.                                                                                                            |
| `response_format`              | JSON mode atau JSON schema, untuk model yang mendukung.                                                                         |

Parameter lain diteruskan ke model apa adanya. Model yang tidak mendukung suatu parameter bisa mengabaikannya atau mengembalikan error.

## Gambar (vision)

[Section titled “Gambar (vision)”](#gambar-vision)

Untuk model dengan kemampuan vision, kirim gambar sebagai bagian dari `content`:

```json
{
  "role": "user",
  "content": [
    {"type": "text", "text": "Ada bug apa di screenshot ini?"},
    {"type": "image_url", "image_url": {"url": "https://contoh.com/error.png"}}
  ]
}
```

URL juga boleh berupa `data:image/png;base64,...`.

## Response

[Section titled “Response”](#response)

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "anthropic/claude-sonnet-5.5",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "let bisa diubah nilainya, const tidak..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 32, "completion_tokens": 58, "total_tokens": 90}
}
```

## Catatan perilaku

[Section titled “Catatan perilaku”](#catatan-perilaku)

* `tool_choice` tanpa `tools` dibuang otomatis supaya request tidak ditolak model.
* Karakter null (`\u0000`) di teks dibuang sebelum diteruskan, karena beberapa model menolaknya.
* `max_tokens` yang sangat kecil dinaikkan ke batas minimum yang diterima model.

# Kode error

> Status HTTP dan bentuk error dari API Vikey, beserta cara menanganinya.

## Bentuk error

[Section titled “Bentuk error”](#bentuk-error)

Endpoint format OpenAI (`/v1/chat/completions`, `/v1/responses`, `/v1/models`):

```json
{
  "error": {
    "message": "Model 'nope/nope' not found (request id: req_01ba...)",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "request_id": "req_01ba..."
  }
}
```

Endpoint format Anthropic (`/v1/messages`):

```json
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Model 'nope' not found (request id: req_2062...)",
    "request_id": "req_2062..."
  }
}
```

Sertakan `request_id` kalau menghubungi support. Dengan id itu kami bisa menelusuri request kamu.

## Status HTTP

[Section titled “Status HTTP”](#status-http)

| Status       | Contoh pesan                                             | Artinya                                             | Yang perlu dilakukan                                                                                                       |
| ------------ | -------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `400`        | `model is required`, `messages is required`              | Request tidak lengkap atau formatnya salah          | Perbaiki body request                                                                                                      |
| `400`        | `Model '...' matches several models` (`ambiguous_model`) | Nama pendek cocok dengan beberapa provider          | Pakai id lengkap yang disebut di pesan                                                                                     |
| `401`        | `API key is required`, `Invalid API key`                 | Key tidak dikirim atau salah                        | Cek header dan salin ulang key                                                                                             |
| `402`        | `Insufficient balance`                                   | Saldo tidak cukup untuk perkiraan biaya request ini | [Top up](/account/top-up/), atau kecilkan `max_tokens`                                                                     |
| `403`        | `API key is inactive`                                    | Key sedang dinonaktifkan                            | Aktifkan lagi di menu **API Keys**                                                                                         |
| `403`        | `This account has been blocked` (`account_blocked`)      | Akun diblokir                                       | Hubungi support                                                                                                            |
| `404`        | `Model '...' not found` (`model_not_found`)              | Model id salah atau model tidak aktif               | Ambil id dari `GET /v1/models`                                                                                             |
| `429`        | Diteruskan dari model                                    | Model tujuan sedang membatasi request               | Tunggu sebentar lalu ulangi                                                                                                |
| `502`, `503` | `The model's supplier is currently unavailable`          | Model sedang bermasalah di sisi penyedia            | Ulangi beberapa saat lagi, atau pakai model lain. [Vikey Auto](/models/vikey-auto/) otomatis pindah ke tingkat berikutnya. |

## Saran penanganan di aplikasi

[Section titled “Saran penanganan di aplikasi”](#saran-penanganan-di-aplikasi)

* Ulangi otomatis untuk `429`, `502`, dan `503`, dengan jeda yang makin panjang.
* Jangan ulangi otomatis untuk `400`, `401`, `402`, `403`, dan `404`. Hasilnya akan sama sampai penyebabnya diperbaiki.
* Untuk `402` di aplikasi yang dipakai banyak orang, tampilkan pesan yang jelas ke admin aplikasi supaya saldo segera diisi.

# Messages (format Anthropic)

> POST /v1/messages, format Anthropic Messages, dipakai Claude Code dan SDK Anthropic.

```http
POST https://api.vikey.ai/v1/messages
```

Format request dan response sama dengan [Messages API Anthropic](https://docs.anthropic.com/en/api/messages). Claude Code dan SDK Anthropic memakai endpoint ini. Semua model teks di Vikey bisa dipanggil lewat format ini, termasuk GPT dan DeepSeek.

## Contoh

[Section titled “Contoh”](#contoh)

```bash
curl https://api.vikey.ai/v1/messages \
  -H "x-api-key: API_KEY_KAMU" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "max_tokens": 1024,
    "system": "Jawab singkat dalam bahasa Indonesia.",
    "messages": [{"role": "user", "content": "Apa beda let dan const di JavaScript?"}]
  }'
```

`Authorization: Bearer API_KEY_KAMU` juga diterima sebagai pengganti `x-api-key`.

## Parameter yang sering dipakai

[Section titled “Parameter yang sering dipakai”](#parameter-yang-sering-dipakai)

| Parameter              | Keterangan                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| `model`                | Wajib. Model id Vikey.                                                                                       |
| `max_tokens`           | Wajib di format Anthropic. Juga dipakai untuk [pengecekan saldo](/models/pricing/#pengecekan-saldo).         |
| `messages`             | Wajib. Pesan `user` dan `assistant`, isinya teks atau blok konten (teks, gambar, `tool_use`, `tool_result`). |
| `system`               | System prompt, berupa teks atau array blok.                                                                  |
| `stream`               | `true` untuk event stream format Anthropic.                                                                  |
| `tools`, `tool_choice` | Tool use dengan format Anthropic.                                                                            |
| `cache_control`        | Penanda cache di blok konten diteruskan ke model yang mendukung.                                             |

## Response

[Section titled “Response”](#response)

```json
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "anthropic/claude-sonnet-5.5",
  "content": [{"type": "text", "text": "let bisa diubah nilainya, const tidak..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 32, "output_tokens": 58}
}
```

Error memakai bentuk Anthropic: `{"type": "error", "error": {"type": "...", "message": "..."}}`. Lihat [Kode error](/api/errors/).

# Daftar model

> GET /v1/models menampilkan model yang bisa dipakai dengan API key kamu, termasuk model Vikey Auto.

```http
GET https://api.vikey.ai/v1/models
```

Menampilkan model aktif yang bisa dipakai dengan API key kamu, termasuk model id [Vikey Auto](/models/vikey-auto/).

```bash
curl https://api.vikey.ai/v1/models -H "Authorization: Bearer API_KEY_KAMU"
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "openai/gpt-6.1-sol",
      "object": "model",
      "owned_by": "organization",
      "context_window": 1000000
    },
    {
      "id": "vikey/agent-gpt",
      "object": "model",
      "owned_by": "vikey",
      "context_window": 1000000,
      "auto_routing": {
        "tiers": {
          "light": "openai/gpt-6-luna",
          "medium": "openai/gpt-5.6-terra",
          "heavy": "openai/gpt-6.1-sol"
        }
      }
    }
  ]
}
```

Contoh di atas dipendekkan. Field `context_window` adalah batas context model dalam token. Model Vikey Auto punya `auto_routing.tiers` yang menunjukkan model di tiap tingkat.

Kalau API key memakai pilihan **sembunyikan nama provider**, `id` ditampilkan tanpa bagian provider (misalnya `claude-sonnet-5.5`) selama namanya tidak bentrok dengan model lain. Lihat [Memilih model](/models/choosing/#menyembunyikan-nama-provider).

Harga per model tidak ada di endpoint ini. Lihat [halaman harga](https://vikey.ai/pricing) atau menu **Models** di dashboard.

# Responses

> POST /v1/responses, format OpenAI Responses, dipakai Codex dan OpenClaw.

```http
POST https://api.vikey.ai/v1/responses
```

Format sama dengan [Responses API OpenAI](https://platform.openai.com/docs/api-reference/responses). Codex dan OpenClaw (dengan `openai-responses`) memakai endpoint ini. Semua model teks di Vikey bisa dipanggil lewat format ini.

## Contoh

[Section titled “Contoh”](#contoh)

```bash
curl https://api.vikey.ai/v1/responses \
  -H "Authorization: Bearer API_KEY_KAMU" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6.1-sol",
    "instructions": "Jawab singkat dalam bahasa Indonesia.",
    "input": "Apa beda let dan const di JavaScript?"
  }'
```

## Parameter yang sering dipakai

[Section titled “Parameter yang sering dipakai”](#parameter-yang-sering-dipakai)

| Parameter           | Keterangan                                         |
| ------------------- | -------------------------------------------------- |
| `model`             | Wajib. Model id Vikey.                             |
| `input`             | Wajib. Teks, atau array item pesan dan hasil tool. |
| `instructions`      | Instruksi sistem.                                  |
| `max_output_tokens` | Batas token output.                                |
| `stream`            | `true` untuk event stream format Responses.        |
| `tools`             | Function tools.                                    |

## Response

[Section titled “Response”](#response)

```json
{
  "id": "resp_...",
  "object": "response",
  "model": "openai/gpt-6.1-sol",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "let bisa diubah nilainya, const tidak..."}]
    }
  ],
  "usage": {"input_tokens": 30, "output_tokens": 55, "total_tokens": 85}
}
```

# Base URL dan autentikasi

> Base URL Vikey untuk format OpenAI, Anthropic, dan Token Plan, cara mengirim API key, dan header opsional.

## Base URL

[Section titled “Base URL”](#base-url)

Pilih base URL sesuai format yang dipakai tool atau SDK kamu.

| Untuk                                                 | Base URL                       | Endpoint yang dipakai                         |
| ----------------------------------------------------- | ------------------------------ | --------------------------------------------- |
| SDK atau tool format OpenAI                           | `https://api.vikey.ai/v1`      | `/chat/completions`, `/responses`, `/models`  |
| SDK atau tool format Anthropic (termasuk Claude Code) | `https://api.vikey.ai`         | `/v1/messages`                                |
| Token Plan                                            | `https://api-plan.vikey.ai/v1` | Sama dengan format OpenAI, model `vikey/plan` |

Perhatikan /v1

SDK OpenAI butuh base URL **dengan** `/v1`. SDK Anthropic dan Claude Code butuh base URL **tanpa** `/v1`, karena mereka menambahkan `/v1/messages` sendiri. Salah satu dari dua ini adalah penyebab error 404 yang paling sering.

## Mengirim API key

[Section titled “Mengirim API key”](#mengirim-api-key)

Kirim key lewat salah satu header ini. Keduanya diterima di semua endpoint.

```http
Authorization: Bearer API_KEY_KAMU
```

```http
x-api-key: API_KEY_KAMU
```

SDK OpenAI memakai `Authorization: Bearer`. SDK Anthropic memakai `x-api-key`. Kamu tidak perlu mengatur header ini sendiri kalau memakai SDK.

## Header opsional

[Section titled “Header opsional”](#header-opsional)

| Header       | Fungsi                                                                                                                                                                                                                                                                                                                            |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-End-User` | Penanda pengguna akhir kamu sendiri (bukan pengguna Vikey), misalnya id pelanggan di aplikasimu. Dicatat bersama data pemakaian. Isi 1 sampai 128 karakter: huruf, angka, garis bawah, titik, titik dua, atau tanda hubung. Nilai yang tidak valid diabaikan, tidak membuat request gagal. Jangan isi dengan email atau nomor HP. |

## Cek saldo lewat API

[Section titled “Cek saldo lewat API”](#cek-saldo-lewat-api)

Saldo bisa dilihat di dashboard. Endpoint `GET /v1/balance` hanya menerima token login dashboard, bukan API key, jadi untuk aplikasi pakai dashboard atau tangani error `402` (lihat [Kode error](/api/errors/)).

# Memilih model

> Cara membaca model id Vikey, nama pendek, daftar model lewat API, dan saran model untuk coding.

## Bentuk model id

[Section titled “Bentuk model id”](#bentuk-model-id)

Model id Vikey ditulis `provider/nama`, misalnya:

* `anthropic/claude-sonnet-5.5`
* `openai/gpt-6.1-sol`
* `deepseek/deepseek-v4.1-flash`
* `moonshot/kimi-k3`

Daftar lengkap beserta harganya ada di [halaman harga](https://vikey.ai/pricing), atau lewat API:

```bash
curl https://api.vikey.ai/v1/models -H "Authorization: Bearer API_KEY_KAMU"
```

## Nama pendek

[Section titled “Nama pendek”](#nama-pendek)

Kamu boleh menulis model tanpa bagian provider, misalnya `claude-sonnet-5.5` atau `deepseek-v4.1-flash`. Vikey mencari model yang namanya cocok:

* Kalau hanya ada satu yang cocok, model itu yang dipakai.
* Kalau nama itu cocok dengan beberapa provider, request ditolak dengan `400` dan kode `ambiguous_model`, beserta daftar id lengkap yang bisa dipilih. Vikey tidak memilihkan, karena harganya bisa berbeda.

Untuk config yang dipakai lama, tulis id lengkap supaya tidak berubah kalau model baru ditambahkan.

## Menyembunyikan nama provider

[Section titled “Menyembunyikan nama provider”](#menyembunyikan-nama-provider)

Di setelan API key ada pilihan untuk menyembunyikan nama provider. Kalau aktif, `GET /v1/models` menampilkan nama pendek (misalnya `claude-sonnet-5.5`) untuk model yang namanya tidak bentrok. Request dengan nama pendek maupun id lengkap tetap diterima.

## Saran untuk coding

[Section titled “Saran untuk coding”](#saran-untuk-coding)

| Kebutuhan                        | Pilihan                                                                                              |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Tidak mau memilih sendiri        | [Vikey Auto](/models/vikey-auto/): `vikey/agent-coding`, `vikey/agent-gpt`, atau `vikey/agent-mocin` |
| Coding harian, kualitas tinggi   | `anthropic/claude-sonnet-5.5` atau `openai/gpt-6.1-sol`                                              |
| Refactor besar, bug sulit        | `anthropic/claude-opus-5.5`                                                                          |
| Tugas ringan dalam jumlah banyak | `deepseek/deepseek-v4.1-flash` atau `openai/gpt-6-luna`                                              |

Harga per model bisa berubah. Angka terbaru selalu ada di [halaman harga](https://vikey.ai/pricing) dan di menu **Models** dashboard.

# Harga dan tagihan

> Cara Vikey menghitung biaya per request, harga cache, pengecekan saldo, dan tempat melihat riwayat pemakaian.

## Bayar sesuai pemakaian

[Section titled “Bayar sesuai pemakaian”](#bayar-sesuai-pemakaian)

Saldo kamu dalam Rupiah dan terpotong otomatis setiap request selesai. Tidak ada biaya bulanan. Harga semua model ada di [halaman harga](https://vikey.ai/pricing), ditulis per 1 juta token.

Biaya satu request:

```text
biaya = (token input x harga input)
      + (token output x harga output)
      + (token cache read x harga cache read)
      + (token cache write x harga cache write)
```

Semua harga per 1 juta token. Angka token persis untuk tiap request ada di `usage` pada response dan di menu **Usage** dashboard.

## Harga cache

[Section titled “Harga cache”](#harga-cache)

Coding agent mengirim ulang awal prompt yang sama di setiap langkah: system prompt, daftar tool, dan riwayat. Bagian yang sama dengan request sebelumnya dibaca dari cache dan ditagih dengan harga **cache read**, yang jauh lebih murah dari harga input biasa. Kolom **Cache read** di halaman harga menunjukkan harganya per model.

Supaya cache bekerja baik:

* Jangan mengubah awal prompt di setiap request, misalnya dengan menaruh jam atau angka acak di system prompt.
* Untuk Claude Code, set `CLAUDE_CODE_ATTRIBUTION_HEADER=0` (lihat [Claude Code](/agents/claude-code/)).

## Pengecekan saldo

[Section titled “Pengecekan saldo”](#pengecekan-saldo)

Sebelum request dijalankan, Vikey menghitung perkiraan biaya maksimalnya dari token input dan batas output (`max_tokens`). Kalau saldo tidak cukup, request ditolak dengan `402` dan tidak ditagih.

Kirim `max_tokens` yang wajar. Batas output yang sangat besar membuat perkiraan biaya ikut besar, sehingga request bisa ditolak padahal saldomu cukup untuk jawaban yang sebenarnya.

## Biaya tambahan

[Section titled “Biaya tambahan”](#biaya-tambahan)

| Bagian                                            | Biaya                                                |
| ------------------------------------------------- | ---------------------------------------------------- |
| Pemilihan model [Vikey Auto](/models/vikey-auto/) | Rp10 per pesan baru, hanya untuk model id Vikey Auto |
| Model gambar                                      | Per gambar, tercantum di halaman harga               |

Tidak ada biaya lain di luar yang tercatat di menu **Usage** dan riwayat transaksi.

## Melihat pemakaian dan tagihan

[Section titled “Melihat pemakaian dan tagihan”](#melihat-pemakaian-dan-tagihan)

| Menu dashboard | Isinya                                             |
| -------------- | -------------------------------------------------- |
| **Overview**   | Ringkasan pemakaian hari ini dan transaksi terbaru |
| **Usage**      | Rincian per model: request, token, dan biaya       |
| **Billing**    | Saldo, top up, riwayat transaksi, invoice          |

Log detail per request disimpan 7 hari. Total harian yang jadi dasar tagihan disimpan permanen.

# Token Plan

> Paket bulanan opsional dengan kuota tetap, di endpoint terpisah api-plan.vikey.ai dengan model vikey/plan.

Token Plan adalah paket bulanan opsional, mulai Rp100.000 per bulan. Kamu bayar sekali di depan lewat QRIS dan dapat kuota pemakaian, tanpa memikirkan harga per token. Token Plan cocok kalau pemakaianmu rutin dan kamu mau biaya yang pasti tiap bulan. Harga paket yang berlaku selalu tampil di menu **Token Plan** dashboard.

## Bedanya dengan bayar sesuai pemakaian

[Section titled “Bedanya dengan bayar sesuai pemakaian”](#bedanya-dengan-bayar-sesuai-pemakaian)

|               | Bayar sesuai pemakaian            | Token Plan                                                |
| ------------- | --------------------------------- | --------------------------------------------------------- |
| Pembayaran    | Top up saldo, terpotong per token | Bayar paket per bulan lewat QRIS                          |
| Base URL      | `https://api.vikey.ai/v1`         | `https://api-plan.vikey.ai/v1`                            |
| Model         | Semua model di katalog            | Satu model id: `vikey/plan`                               |
| Pilihan model | Kamu pilih, atau pakai Vikey Auto | Vikey memilih tingkat kemampuan yang pas untuk tiap pesan |
| Perpanjangan  | Tidak ada langganan               | Tidak diperpanjang otomatis                               |

## Kuota

[Section titled “Kuota”](#kuota)

Token Plan memakai kuota adil (fair usage), bukan dihitung per token seperti bayar sesuai pemakaian. Ada dua jendela waktu:

| Jendela    | Cara kerja                                                           |
| ---------- | -------------------------------------------------------------------- |
| Per 5 jam  | Dihitung mundur dari pemakaian terakhir, bukan reset di jam tertentu |
| Per minggu | Sama, dihitung mundur dari pemakaian terakhir                        |

Pemakaian tiap jendela dan kapan pulih penuh bisa dilihat di menu **Token Plan**, lalu **Usage Limit**. Request besar memakai kuota lebih banyak dari request kecil.

Kalau salah satu jendela penuh, request ditolak sampai kuota pulih. Kalau kamu tidak mau menunggu, aktifkan **Lanjut pakai saldo kalau limit tercapai** di halaman yang sama: request tambahan tetap jalan dan ditagih dari saldo biasa, sesuai harga bayar sesuai pemakaian model yang mengerjakannya ditambah biaya pemilihan model. Kalau saldo juga habis, request ditolak. Pilihan ini mati secara bawaan.

## Memakai Token Plan

[Section titled “Memakai Token Plan”](#memakai-token-plan)

Semua panduan coding agent di docs ini berlaku, dengan dua perbedaan:

1. Base URL diganti `https://api-plan.vikey.ai/v1` (format OpenAI) atau `https://api-plan.vikey.ai` (format Anthropic).
2. Model selalu `vikey/plan`, termasuk untuk tugas latar belakang seperti judul sesi.

Contoh Claude Code:

\~/.claude/settings.json

```json
{
  "model": "vikey/plan",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api-plan.vikey.ai",
    "ANTHROPIC_AUTH_TOKEN": "API_KEY_KAMU",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "vikey/plan"
  }
}
```

Contoh Codex:

\~/.codex/config.toml

```toml
model = "vikey/plan"
model_provider = "vikey-plan"


[model_providers.vikey-plan]
name = "Vikey Token Plan"
base_url = "https://api-plan.vikey.ai/v1"
env_key = "VIKEY_API_KEY"
wire_api = "responses"
```

Snippet siap salin untuk tool lain ada di menu **Token Plan** dashboard.

Perhatian

Endpoint Token Plan hanya melayani `vikey/plan`. Model id lain seperti `openai/gpt-6-luna` tidak tersedia di sana, jadi jangan pakai model lain untuk tugas latar belakang saat memakai Token Plan.

## Ketentuan

[Section titled “Ketentuan”](#ketentuan)

* Pembayaran final dan tidak bisa direfund setelah berhasil.
* Untuk organisasi, hanya owner yang bisa membeli paket.
* Paket bisa dihadiahkan ke akun lain. Kalau penerima sudah punya paket yang sama, masa aktifnya diperpanjang.

# Vikey Auto

> Satu model id yang memilih model ringan, sedang, atau berat untuk tiap tugas, dan memangkas riwayat yang sudah tidak dipakai.

Vikey Auto adalah model id yang isinya tiga model: ringan, sedang, dan berat. Setiap kali kamu mengirim pesan baru, Vikey memilih model yang pas untuk tugas itu. Pertanyaan singkat dijawab model ringan, satu fitur dikerjakan model sedang, refactor besar dikerjakan model berat.

## Model id yang tersedia

[Section titled “Model id yang tersedia”](#model-id-yang-tersedia)

| Model id             | Ringan              | Sedang                   | Berat                    |
| -------------------- | ------------------- | ------------------------ | ------------------------ |
| `vikey/agent-gpt`    | GPT-6 Luna          | GPT-5.6 Terra            | GPT-6.1 Sol              |
| `vikey/agent-coding` | Claude Haiku 5.5    | Claude Sonnet 5.5        | Claude Opus 5.5          |
| `vikey/agent-mocin`  | DeepSeek V4.1 Flash | DeepSeek V4.1 Flash 1017 | DeepSeek V4.1 Flash 1017 |

Pakai seperti model biasa, misalnya `"model": "vikey/agent-gpt"` di request, atau `claude --model vikey/agent-coding`.

Daftar terbaru dan model di tiap tingkat bisa dilihat di menu **Auto Routing** dashboard. Di menu yang sama kamu bisa mengganti model untuk tiap tingkat sesuai selera.

## Kapan memakai tingkat apa

[Section titled “Kapan memakai tingkat apa”](#kapan-memakai-tingkat-apa)

| Tingkat | Contoh tugas                                                                                                  |
| ------- | ------------------------------------------------------------------------------------------------------------- |
| Ringan  | Pertanyaan, menjalankan test atau perintah, commit, typo, perubahan kecil satu baris                          |
| Sedang  | Satu fitur, halaman, endpoint, atau script. Bug yang penyebabnya terlihat.                                    |
| Berat   | Aplikasi utuh, perubahan di banyak file, bug yang penyebabnya belum jelas, keamanan, pembayaran, migrasi data |

Penjelasan lengkap tiap tingkat juga ada di menu **Auto Routing** dashboard.

## Aturan pemilihan

[Section titled “Aturan pemilihan”](#aturan-pemilihan)

* **Dipilih sekali per pesan baru.** Langkah-langkah tool di dalam satu tugas (agent membaca file, menjalankan perintah, lalu lanjut) tetap memakai model yang sama sampai tugas selesai. Model tidak berganti di tengah tugas.
* **Request pembantu tidak dihitung.** Request kecil dari agent seperti membuat judul sesi langsung memakai model ringan dan tidak dikenai biaya pemilihan.
* **Kalau model bermasalah,** request otomatis dialihkan ke tingkat berikutnya.
* **Kalau pemilihan sedang tidak tersedia,** request dikerjakan model sedang dan tidak dikenai biaya pemilihan.

## Pemangkasan riwayat

[Section titled “Pemangkasan riwayat”](#pemangkasan-riwayat)

Coding agent mengirim ulang seluruh riwayat dan hasil tool di setiap langkah. Lama-lama sebagian besar isinya sudah tidak dipakai, misalnya isi file yang dibaca untuk tugas sebelumnya.

Saat kamu mengirim pesan baru, Vikey Auto juga menilai hasil tool lama yang besar. Yang sudah tidak relevan diganti dengan catatan satu baris sebelum dikirim ke model. Pesan kamu sendiri tidak dihapus. Untuk percakapan biasa (bukan agent), riwayat lama dilepas saat topik berganti.

Di tes kami dengan coding agent sungguhan, prompt giliran berikutnya mengecil sekitar 51% di Claude Code dan opencode, dan 53% di Codex. Hasilnya tergantung panjang sesi: paling terasa di sesi panjang dan saat topik berganti, kecil di sesi pendek.

Selama agent masih mengerjakan satu tugas, tidak ada yang dipangkas, supaya cache tetap jalan. Pengecualiannya, kalau prompt sudah sangat besar (di atas sekitar 80 ribu token), Vikey bisa memangkas di tengah tugas.

Isi prompt tidak disimpan

Untuk mengingat apa yang sudah dinilai, Vikey hanya menyimpan sidik jari pendek (hash) selama 6 jam. Isi prompt, kode, dan jawaban tidak disimpan.

## Biaya

[Section titled “Biaya”](#biaya)

| Bagian                      | Biaya                                                      |
| --------------------------- | ---------------------------------------------------------- |
| Token                       | Sesuai harga model yang mengerjakan tugas itu              |
| Pemilihan model             | Rp10 per pesan baru                                        |
| Pemangkasan di tengah tugas | Rp10 per pemangkasan, hanya saat prompt sudah sangat besar |

Biaya pemilihan hanya ditagih kalau request berhasil. Di menu **Usage** dan riwayat transaksi, biaya ini tercatat sebagai baris terpisah dengan model `vikey/decision`.

Menu **Auto Routing** di dashboard menunjukkan berapa yang sudah kamu hemat dibanding harga resmi, termasuk token yang dipangkas.

Kapan tidak perlu Vikey Auto

Untuk satu request kecil yang berdiri sendiri, misalnya klasifikasi teks pendek, biaya pemilihan Rp10 bisa lebih besar dari selisih harganya. Pakai model tetap untuk kasus seperti itu.

# Quickstart

> Dari daftar akun sampai request pertama ke Vikey dalam lima langkah.

1. **Daftar akun.** Buka [vikey.ai/register](https://vikey.ai/register). Kamu bisa daftar dengan email atau Google. Pendaftaran lewat email minta kode 6 digit yang dikirim ke email kamu.

2. **Top up saldo.** Di dashboard, buka **Billing**, lalu **Top up**. Bayar lewat QRIS dari e-wallet atau mobile banking apa pun, mulai Rp10.000. Saldo masuk otomatis setelah pembayaran terkonfirmasi, biasanya dalam hitungan detik. Detailnya ada di [Top up dan saldo](/account/top-up/).

3. **Buat API key.** Buka **API Keys** di dashboard, lalu buat key baru dan beri nama, misalnya `laptop` atau `claude-code`. Simpan key ini di tempat aman. Key inilah yang kamu pakai di semua request.

4. **Kirim request pertama.** Ganti `API_KEY_KAMU` dengan key dari langkah 3.

   * curl

     ```bash
     curl https://api.vikey.ai/v1/chat/completions \
       -H "Authorization: Bearer API_KEY_KAMU" \
       -H "Content-Type: application/json" \
       -d '{
         "model": "openai/gpt-6-luna",
         "messages": [{"role": "user", "content": "Halo, kamu model apa?"}]
       }'
     ```

   * Python

     ```python
     from openai import OpenAI


     client = OpenAI(base_url="https://api.vikey.ai/v1", api_key="API_KEY_KAMU")
     reply = client.chat.completions.create(
         model="openai/gpt-6-luna",
         messages=[{"role": "user", "content": "Halo, kamu model apa?"}],
     )
     print(reply.choices[0].message.content)
     ```

   * Node.js

     ```js
     import OpenAI from 'openai'


     const client = new OpenAI({ baseURL: 'https://api.vikey.ai/v1', apiKey: 'API_KEY_KAMU' })
     const reply = await client.chat.completions.create({
       model: 'openai/gpt-6-luna',
       messages: [{ role: 'user', content: 'Halo, kamu model apa?' }],
     })
     console.log(reply.choices[0].message.content)
     ```

   Response-nya sama dengan format OpenAI: ada `choices` berisi jawaban dan `usage` berisi jumlah token.

5. **Cek pemakaian.** Buka **Usage** di dashboard. Setiap request tercatat per model, lengkap dengan token dan biayanya dalam Rupiah.

Mau langsung pakai di coding agent?

Lanjut ke panduan [Claude Code](/agents/claude-code/), [Codex CLI](/agents/codex/), atau [opencode](/agents/opencode/). Kalau tidak mau pusing memilih model, pakai [Vikey Auto](/models/vikey-auto/).

## Kalau request pertama gagal

[Section titled “Kalau request pertama gagal”](#kalau-request-pertama-gagal)

| Yang kamu lihat                      | Artinya                                        | Yang perlu dilakukan                      |
| ------------------------------------ | ---------------------------------------------- | ----------------------------------------- |
| `401` dengan `Invalid API key`       | Key salah atau ada spasi ikut tersalin         | Salin ulang key dari dashboard            |
| `402` dengan `Insufficient balance`  | Saldo habis atau tidak cukup untuk request ini | Top up, lalu kirim ulang                  |
| `404` dengan `Model '...' not found` | Model id salah atau model tidak aktif          | Ambil id yang benar dari `GET /v1/models` |

Daftar lengkap ada di [Kode error](/api/errors/).

# Setup lewat AI agent

> Prompt siap tempel supaya coding agent kamu membaca docs Vikey dan mengatur koneksinya sendiri.

Coding agent bisa membaca docs ini sendiri. Tempel salah satu prompt di bawah ke agent kamu (Claude Code, Codex, opencode, atau yang lain), lalu agent akan menulis config-nya dan memberi tahu langkah yang perlu kamu lakukan sendiri.

API key tetap kamu yang isi

Prompt di bawah meminta agent memakai variabel environment `VIKEY_API_KEY`, bukan menulis key langsung ke file yang bisa ter-commit. Set variabel itu sendiri di terminal: `export VIKEY_API_KEY=API_KEY_KAMU`.

## Prompt umum

[Section titled “Prompt umum”](#prompt-umum)

```text
Baca https://docs.vikey.ai/llms.txt dan halaman docs yang relevan untuk tool yang
sedang kamu pakai (tambahkan ".md" di akhir URL halaman untuk versi Markdown).
Lalu atur tool ini supaya memakai Vikey:
- API key ada di variabel environment VIKEY_API_KEY. Jangan tulis key ke file
  yang ada di dalam repository.
- Model utama: vikey/agent-coding.
- Ikuti config di docs persis, termasuk setelan model untuk tugas latar belakang.
Setelah selesai, tunjukkan file yang kamu ubah dan perintah untuk mengecek koneksi.
```

## Prompt per tool

[Section titled “Prompt per tool”](#prompt-per-tool)

Kalau kamu sudah tahu tool-nya, arahkan agent langsung ke halamannya. Lebih cepat dan lebih sedikit token.

| Tool                        | Halaman untuk agent                           |
| --------------------------- | --------------------------------------------- |
| Claude Code                 | `https://docs.vikey.ai/agents/claude-code.md` |
| Codex CLI dan Codex Desktop | `https://docs.vikey.ai/agents/codex.md`       |
| opencode                    | `https://docs.vikey.ai/agents/opencode.md`    |
| Cline, Roo Code, Kilo Code  | `https://docs.vikey.ai/agents/cline.md`       |
| OpenClaw                    | `https://docs.vikey.ai/agents/openclaw.md`    |
| Hermes                      | `https://docs.vikey.ai/agents/hermes.md`      |

Contoh:

```text
Baca https://docs.vikey.ai/agents/codex.md lalu atur Codex di mesin ini supaya
memakai Vikey dengan model vikey/agent-gpt. API key ada di VIKEY_API_KEY.
```

## File untuk AI

[Section titled “File untuk AI”](#file-untuk-ai)

| URL                                | Isi                                                             |
| ---------------------------------- | --------------------------------------------------------------- |
| [`/llms.txt`](/llms.txt)           | Daftar semua halaman dengan ringkasannya                        |
| [`/llms-full.txt`](/llms-full.txt) | Seluruh isi docs dalam satu file Markdown                       |
| `URL halaman` + `.md`              | Satu halaman sebagai Markdown, misalnya `/models/vikey-auto.md` |
| `/en/` + halaman + `.md`           | Versi bahasa Inggris, misalnya `/en/agents/claude-code.md`      |

# Troubleshooting

> Masalah yang paling sering muncul saat memakai Vikey dan cara memperbaikinya.

Mulai dari tes paling sederhana. Kalau perintah ini berhasil, key dan saldo kamu beres, dan masalahnya ada di config tool:

```bash
curl https://api.vikey.ai/v1/chat/completions \
  -H "Authorization: Bearer API_KEY_KAMU" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-6-luna", "max_tokens": 16, "messages": [{"role": "user", "content": "ping"}]}'
```

## Masalah umum

[Section titled “Masalah umum”](#masalah-umum)

| Gejala                                            | Penyebab paling mungkin                                                               | Solusi                                                                                                                       |
| ------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `404` di semua request                            | Base URL salah. SDK OpenAI butuh `/v1`, SDK Anthropic dan Claude Code tidak.          | Lihat [Base URL](/base-url/)                                                                                                 |
| `401 Invalid API key`                             | Key salah, ada spasi, atau key milik akun lain                                        | Salin ulang dari menu **API Keys**                                                                                           |
| `401` padahal key benar                           | Tool mengirim key di header yang salah, atau variabel environment belum terbaca       | Cek panduan tool kamu di bagian Coding agent                                                                                 |
| `402 Insufficient balance`                        | Saldo habis atau `max_tokens` terlalu besar untuk saldo yang tersisa                  | [Top up](/account/top-up/), atau kecilkan `max_tokens`                                                                       |
| `403 API key is inactive`                         | Key dinonaktifkan                                                                     | Aktifkan lagi di menu **API Keys**                                                                                           |
| `Model '...' not found`                           | Model id salah ketik, atau tool mengirim nama model bawaannya                         | Pakai id dari [halaman harga](https://vikey.ai/pricing). Untuk Claude Code, pasang [`modelOverrides`](/agents/claude-code/). |
| `ambiguous_model`                                 | Nama pendek cocok dengan beberapa provider                                            | Pakai id lengkap seperti `deepseek/deepseek-v4.1-flash`                                                                      |
| Codex: `wire_api = "chat" is no longer supported` | Config Codex lama                                                                     | Ganti jadi `wire_api = "responses"`, lihat [Codex](/agents/codex/)                                                           |
| opencode: `Model not found: vikey/...`            | Format `providers` yang belum didukung, atau model belum ada di `models`              | Pakai format di [opencode](/agents/opencode/)                                                                                |
| Claude Code: diminta login                        | Key ada di settings proyek, bukan di settings user atau shell                         | Lihat [Claude Code](/agents/claude-code/)                                                                                    |
| Biaya lebih besar dari perkiraan                  | Prompt panjang dikirim ulang tanpa cache, atau model mahal dipakai untuk tugas ringan | Cek menu **Usage** per model, pertimbangkan [Vikey Auto](/models/vikey-auto/)                                                |
| Jawaban terputus di tengah                        | Batas `max_tokens` tercapai                                                           | Naikkan `max_tokens`                                                                                                         |
| `502` atau `503`                                  | Model sedang bermasalah di sisi penyedia                                              | Ulangi sebentar lagi, atau pakai model lain                                                                                  |

## Masih bermasalah?

[Section titled “Masih bermasalah?”](#masih-bermasalah)

Hubungi kami lewat [Telegram](https://t.me/+gAhmT7YKbtRmZWM9) atau [WhatsApp](https://wa.me/6287780232611). Sertakan:

* `request_id` dari pesan error, kalau ada
* Tool dan versinya, misalnya Claude Code 2.1.323
* Model id yang dipakai
* Waktu kejadian

Jangan kirim API key kamu ke siapa pun, termasuk ke support.