TokenomixAI API

Endpoint TokenomixAI mengikuti format OpenAI. Kode dan tool yang sudah mendukung OpenAI bisa langsung dipakai dengan mengganti base URL dan API key.

Quickstart

1. Beli paket di halaman pricing. Setelah pembayaran masuk, kamu menerima API key sk-tkx-… dan hashtag akun #TKX-XXXXXX.
2. Set base URL ke https://api.tokenomixai.com/v1.
3. Kirim request seperti ke OpenAI.

curl https://api.tokenomixai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "stream": true,
    "messages": [{"role": "user", "content": "Halo!"}]
  }'

Belum punya tool? Install dengan 1 command

Kalau kamu belum punya coding agent, command di bawah menginstall OpenCode atau Claude Code sekaligus mengisi base URL dan API key. Script mengecek key dulu, lalu mem-backup config lama sebelum mengisi bagian TokenomixAI. Setting lain di config kamu (MCP, plugin, provider lain) tetap dipertahankan; config yang berisi komentar ditulis ulang (backup tetap ada). Untuk balik ke config semula, jalankan command yang sama dengan tambahan --restore (Linux/macOS) atau $env:RESTORE="1" (Windows), lalu /logout dan /login di dalam tool. Isi script bisa kamu baca sebelum dijalankan: opencode.sh, opencode.ps1, claude.sh, claude.ps1.

Pakai di aplikasi desktop

Tidak ada command terpisah. Jalankan command di atas sekali di Terminal atau PowerShell. Aplikasi desktop membaca config yang sama:

• OpenCode Desktop: pakai command OpenCode. Tutup lalu buka lagi aplikasinya, provider TokenomixAI dan model default langsung terpilih.
• Claude Code di VS Code: pakai command Claude Code. Tutup lalu buka lagi VS Code, buka panel Claude Code, lalu langsung chat. Tidak perlu login akun Claude.

Aplikasi Claude Desktop belum bisa dipakai, baik tab Chat maupun tab Code. Tab Code di aplikasi itu selalu memakai akun Claude yang sedang login, jadi setting dari command di atas tidak terbaca. Pakai Claude Code di Terminal atau VS Code.

Autentikasi

Kirim key di header Authorization: Bearer sk-tkx-…. Key hanya ditampilkan sekali saat diterbitkan. TokenomixAI menyimpan key dalam bentuk hash, jadi key yang hilang tidak bisa ditampilkan ulang, hanya bisa di-rotate.

Endpoint

Endpoint lain di luar daftar ini mengembalikan 404.

Tool use (function calling)

Tool use bisa dipakai di kedua endpoint dengan format standar masing-masing. Definisi tool, tool call dari model, dan hasil tool diteruskan apa adanya, juga saat stream: true. Claude Code, OpenCode, dan agent di Setup tool memakai fitur ini di balik layar.

Pilih model yang mendukung tool calling. Kalau model membalas teks biasa tanpa tool call, coba model lain dari katalog.

Chat Completions (format OpenAI)

Kirim daftar tool di field tools. tool_choice opsional ("auto", "none", "required", atau nama function tertentu).

curl https://api.tokenomixai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tkx-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{ "role": "user", "content": "What is the weather in Jakarta right now?" }],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Kalau model memanggil tool, jawabannya berisi choices[0].message.tool_calls dengan finish_reason: "tool_calls". arguments berupa string JSON. Jalankan tool di sisi kamu, lalu kirim ulang percakapan: pesan assistant tadi apa adanya, ditambah satu pesan role: "tool" per tool call.

"messages": [
  { "role": "user", "content": "What is the weather in Jakarta right now?" },
  { "role": "assistant", "content": null, "tool_calls": [{
      "id": "call_1", "type": "function",
      "function": { "name": "get_weather", "arguments": "{\"city\":\"Jakarta\"}" }
  }] },
  { "role": "tool", "tool_call_id": "call_1", "content": "{\"temp_c\":31,\"condition\":\"sunny\"}" }
]

Messages (format Anthropic)

Field tools berisi name, description, dan input_schema. max_tokens wajib di format ini.

curl https://api.tokenomixai.com/v1/messages \
  -H "Authorization: Bearer sk-tkx-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "What is the weather in Jakarta right now?" }],
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "input_schema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }]
  }'

Model membalas block tool_use di content dengan stop_reason: "tool_use". Kirim hasilnya sebagai block tool_result di pesan user berikutnya, dengan tool_use_id yang sama.

"messages": [
  { "role": "user", "content": "What is the weather in Jakarta right now?" },
  { "role": "assistant", "content": [
      { "type": "tool_use", "id": "toolu_1", "name": "get_weather", "input": { "city": "Jakarta" } }
  ] },
  { "role": "user", "content": [
      { "type": "tool_result", "tool_use_id": "toolu_1", "content": "{\"temp_c\":31,\"condition\":\"sunny\"}" }
  ] }
]

Setup tool

Cursor

1. Buka Settings → Models.
2. Isi OpenAI API Key dengan key sk-tkx-…, aktifkan Override OpenAI Base URL dan isi https://api.tokenomixai.com/v1.
3. Tambahkan nama model dari katalog (misalnya MODEL_ID) sebagai custom model.

Cline / Roo Code

Pilih API Provider OpenAI Compatible, isi Base URL https://api.tokenomixai.com/v1, API Key, dan Model ID dari katalog.

Zed

// ~/.config/zed/settings.json
{
  "language_models": {
    "openai": {
      "api_url": "https://api.tokenomixai.com/v1",
      "available_models": [
        // max_tokens: sesuaikan dengan konteks model
        { "name": "MODEL_ID", "display_name": "MODEL_ID (TokenomixAI)", "max_tokens": 128000 }
      ]
    }
  }
}
// API key diisi lewat Agent Panel → Settings → OpenAI.

OpenCode

Cara tercepat: install 1 command. Manual:

1. Install: curl -fsSL https://opencode.ai/install | bash (Windows: npm install -g opencode-ai).
2. Buat config di ~/.config/opencode/opencode.json:

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenomixai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenomixAI",
      "options": {
        "baseURL": "https://api.tokenomixai.com/v1",
        "apiKey": "{env:TOKENOMIXAI_API_KEY}"
      },
      "models": {
        "MODEL_ID": { "name": "MODEL_ID" },
        "MODEL_ALT": { "name": "MODEL_ALT" }
      }
    }
  }
}

3. Set TOKENOMIXAI_API_KEY di environment kamu, lalu jalankan opencode.

Muncul error upstream request failed: invalid credential atau 401? Key tidak terbaca atau salah: cek key tersalin utuh (diawali sk-tkx-, tanpa spasi), pastikan TOKENOMIXAI_API_KEY ada di terminal yang menjalankan OpenCode, atau jalankan ulang install 1 command untuk mengisi key lagi. Key yang sudah di-rotate tidak berlaku lagi.

Claude Code

Cara tercepat: install 1 command. Panduan lengkap per sistem operasi ada di Cara install Claude Code. Manual:

1. Install (butuh Node.js): npm install -g @anthropic-ai/claude-code.
2. Isi ~/.claude/settings.json. Base URL tanpa /v1, karena Claude Code menambahkan /v1/messages sendiri:

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.tokenomixai.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-tkx-…",
    "ANTHROPIC_MODEL": "MODEL_ID",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MODEL_FAST",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MODEL_ID",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "MODEL_ID",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000"
  }
}

3. Jalankan claude. Ganti model dengan /model haiku, sonnet, atau opus (dipetakan ke model di atas, bukan model Claude asli). Model lain dari katalog, termasuk Claude, dipilih dengan /model <model-id>.
4. Peringatan Model "…" isn't recognized · context assumed … itu normal: Claude Code belum mengenal nama model di katalog, modelnya tetap jalan. Baris CLAUDE_CODE_AUTO_COMPACT_WINDOW membuat percakapan diringkas otomatis di 200rb token, jadi model dengan context lebih kecil tidak error dan chat panjang tidak menghabiskan kuota sebesar seluruh context di tiap pesan.

9router

1. Install dan jalankan: npm install -g 9router lalu 9router. Dashboard ada di http://localhost:20128/dashboard.
2. Buka Providers, lalu Add OpenAI Compatible.
3. Isi Prefix dengan tknx (bebas, dipakai sebagai awalan ID model) dan API Type dengan Chat Completions.
4. Isi Base URL dengan https://api.tokenomixai.com/v1 dan API Key dengan sk-tkx-….
5. Isi Model ID dengan model dari katalog (misalnya MODEL_ID), klik Check sampai muncul Valid, lalu Create.

Model dipanggil dengan ID tknx/<model-id>, dan bisa dimasukkan ke combo atau routing 9router seperti provider lain.

Hermes

Hermes bisa langsung ke TokenomixAI sebagai provider custom, tanpa perantara. Install: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash, lalu isi dua file berikut dan jalankan hermes.

# ~/.hermes/config.yaml
model:
  provider: custom
  base_url: https://api.tokenomixai.com/v1
  default: MODEL_ID    # model ID dari katalog, jangan auto
  key_env: ROUTER_API_KEY

# ~/.hermes/.env
ROUTER_API_KEY=sk-tkx-…

Nama variabel di key_env bebas, asal sama dengan yang kamu isi di .env. Kalau kamu sudah memakai 9router, Hermes juga bisa diarahkan ke 9router yang punya provider TokenomixAI di atas.

n8n

Pakai node AI Agent versi 3 ke atas, lalu pilih salah satu chat model:

• Anthropic Chat Model (paling mudah): buat credential Anthropic, isi API Key sk-tkx-… dan Base URL https://api.tokenomixai.com (tanpa /v1).
• OpenAI Chat Model: buat credential OpenAI, isi API Key sk-tkx-… dan Base URL https://api.tokenomixai.com/v1, tanpa garis miring di akhir. Node ini memakai Responses API secara default; kalau workflow kamu dapat 404, buka Options lalu matikan Use Responses API.

Tulis ID model dari katalog secara langsung (misalnya model GLM), jangan auto: auto menambah banyak input token di tiap request. Node chat, AI Agent dan tool calling bisa dipakai. Embeddings belum tersedia, jadi node Embeddings dan vector store belum bisa memakai key ini.

OpenClaw & agent lain

Pilih provider custom / OpenAI-compatible (API chat/completions), isi Base URL https://api.tokenomixai.com/v1, API Key sk-tkx-…, dan Model ID dari katalog. Agent memakai tool calling, jadi pilih model yang mendukungnya.

Stuck pas setup? Tanya di grup Telegram, terbuka untuk umum.

Model baru

Begitu model baru muncul di katalog, model itu langsung bisa dipakai dengan key yang sama. Panggil dengan ID persis seperti di katalog. Yang perlu disesuaikan hanya tool yang menyimpan daftar model sendiri:

Command update OpenCode memakai key yang sudah tersimpan di config, mem-backup config dulu, lalu hanya mengganti daftar model TokenomixAI. Model default, provider lain, dan setting lain tidak disentuh. Butuh python3 (Linux/macOS) atau Node.js (Windows).

Linux / macOS:

bash <(curl -fsSL https://tokenomixai.com/install/opencode.sh) --update-models

Windows (PowerShell):

$env:UPDATE_MODELS="1"; irm https://tokenomixai.com/install/opencode.ps1 | iex

Model & multiplier

Token yang terpotong dihitung dengan:

token_terpakai = (prompt_tokens + completion_tokens) × multiplier

Contoh: model dengan multiplier 2× memotong 2.000 token untuk task 1.000 token. Daftar model dan multiplier di bawah ini live dari server, sama isinya dengan katalog model di homepage.

Rate limit

Batasnya 600 request per menit per akun (dibagi semua key kamu, termasuk key tambahan), dihitung dengan algoritma token bucket (burst sampai 600 request). Batas ini berlaku untuk semua model sekaligus, bukan per model. Gateway tidak membatasi jumlah request concurrent. Saat batas terlampaui, gateway mengembalikan 429 dengan header Retry-After (detik).

Saat sebuah model sedang ramai, request ke model itu sesekali juga bisa dibalas 429 walaupun key kamu masih di bawah batas. Untuk agent atau trafik async, pasang retry dengan backoff. Ada kendala soal limit? Hubungi kami.

Kode error

Error mengikuti format OpenAI: {"error": {"message", "type", "code"}}.

Cek sisa kuota

Sisa kuota selalu bisa dilihat di Portal. Supaya tidak perlu bolak-balik ke Portal, sisa kuota juga bisa tampil langsung di tool kamu:

Baris di VS Code butuh Claude Code versi terbaru. Kalau installer memberi tahu versimu belum mendukung, update Claude Code lalu jalankan ulang command install. Sudah install sebelum fitur ini ada? Jalankan ulang command install untuk memasangnya. Tanpa installer: ketik /plugin install tokenomixai --marketplace sagarasea/tokenomixai-claude di dalam Claude Code.

curl https://api.tokenomixai.com/v1/quota -H "Authorization: Bearer sk-tkx-…"

{
  "object": "quota",
  "hashtag": "#TKX-XXXXXX",
  "status": "active",
  "remainingTokens": 3800000000,
  "maxTokens": 5000000000,
  "usagePercent": 24,
  "expiresAt": "2026-12-12T00:00:00.000Z",
  "low": false,
  "checkedAt": "2026-11-08T07:00:00.000Z",
  "stale": false
}

low bernilai true saat sisa 10% atau kurang. status berisi exhausted saat kuota habis atau masa aktif lewat. Angka disimpan sementara 60 detik (stale: true = angka terakhir yang tersimpan karena data terbaru sedang tidak bisa diambil). Batasnya 60 request per menit per IP, dan endpoint ini tidak memotong kuota.

Hemat kuota untuk request kecil

Setiap request dipotong minimal sekitar 1.000 token (sebelum multiplier), sekecil apa pun isinya. Untuk tugas kecil yang banyak, misalnya satu item di n8n, satu sel spreadsheet, atau satu pesan bot, gabungkan beberapa item dalam satu request daripada mengirimnya satu per satu.

Tulis ID model langsung dari katalog, jangan auto. Model auto menambah sekitar 17 ribu input token di tiap request, jadi paling boros untuk request kecil.

Portal & top-up

Masuk ke Portal dengan API key untuk melihat sisa kuota, masa aktif, riwayat request, rotate key, serta membuat dan mencabut key tambahan (satu per tool atau perangkat, maks 5, kuota tetap sama). Untuk menambah kuota, beli paket dengan pilihan Top-up dan isi hashtag akun kamu (format #TKX-XXXXXX). Key tidak berubah saat top-up.

Data yang dicatat

Untuk setiap request, gateway mencatat: waktu, endpoint, model, status HTTP, latensi, dan jumlah token prompt/completion. Isi prompt dan jawaban tidak disimpan oleh gateway TokenomixAI. Request tetap diproses oleh penyedia model upstream untuk menghasilkan jawaban. Detail di Kebijakan Privasi.