API v1

Dokumentasi Gateway

Octafy menyediakan endpoint chat completions yang kompatibel dengan format OpenAI. Satu API key berlaku untuk seluruh katalog model; billing memakai saldo wallet, kuota paket token, atau keduanya.

Quickstart

Buat akun, top up saldo, lalu buat API key di dashboard. Secret hanya ditampilkan sekali.

bash

export OCTAFY_API_KEY="sk_live_xxxxxxxxx"
export OCTAFY_BASE_URL="https://api.octafy.xyz/v1"

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.octafy.xyz/v1",
    api_key="sk_live_xxxxxxxxx",
)

resp = client.chat.completions.create(
    model="octa/deepseek-v4.1-flash-1017",
    messages=[{"role": "user", "content": "Jelaskan Octafy"}],
)

print(resp.choices[0].message.content)
print(resp.usage.total_tokens)

Daftar model

Gunakan API key untuk mengambil katalog model yang aktif. Endpoint ini tidak memotong saldo dan tidak memerlukan body request.

bash

curl "https://api.octafy.xyz/v1/models"   -H "Authorization: Bearer $OCTAFY_API_KEY"

json

{
  "models": [
    {
      "public_id": "octa/deepseek-4.1-flash-1017",
      "display_name": "DeepSeek 4.1 Flash",
      "context_window": 128000,
      "available": true,
      "pricing": {
        "input_price_idr_per_mtok": 2500,
        "output_price_idr_per_mtok": 3489,
        "cached_input_price_idr_per_mtok": 0,
        "min_charge_idr": 0
      }
    }
  ]
}

Model ID publik selalu memakai namespace octa/. Untuk katalog tanpa autentikasi, gunakan GET /v1/public/models. Endpoint yang sama juga menerima JWT customer dari dashboard.

Autentikasi

Kirim API key pada header Authorization header. Dashboard memakai JWT; endpoint gateway hanya menerima API key berawalan sk_.

http

Authorization: Bearer sk_live_xxxxxxxxx

Jangan menaruh API key di frontend publik. Panggil gateway dari server Anda.

Zero data retention

Isi prompt dan respons hanya berada di memori selama request berlangsung. Kami tidak menulisnya ke database atau log aplikasi; yang disimpan hanya metadata seperti jumlah token, biaya, latensi, dan status.

Metadata billing dan audit tetap disimpan untuk operasional dan kewajiban hukum. Lihat halaman Keamanan untuk detail.

Baca kebijakan keamanan →

Agentic tools

OpenCode, Cline, Roo Code, Continue, dan tools lain yang mendukung OpenAI-compatible provider dapat memakai Octafy langsung. Gateway meneruskan tools, tool_choice, parallel_tool_calls, serta respons tool_calls, termasuk saat streaming.

Gunakan API key dari dashboard. Jangan menaruh key di konfigurasi yang ikut ter-commit; gunakan environment variable.

OpenCode

Tambahkan custom provider OpenAI-compatible di opencode.jsonc, lalu pilih model lewat /models. Daftarkan model secara eksplisit karena katalog Octafy tidak berasal dari models.dev.

bash

export OCTAFY_API_KEY="sk_live_xxxxxxxxx"

jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "octafy/octa/glm-5.3-flash",
  "providers": {
    "octafy": {
      "name": "Octafy",
      "env": ["OCTAFY_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.octafy.xyz/v1"
      },
      "models": {
        "octa/glm-5.3-flash": { "name": "GLM-5.3 Flash" },
        "octa/glm-5.3": { "name": "GLM-5.3" },
        "octa/deepseek-4.1-flash": { "name": "DeepSeek V4.1 Flash" },
        "octa/kimi-k3": { "name": "Kimi-K3" }
      }
    }
  }
}

Claude Code

Claude Code memakai Anthropic Messages API, sedangkan Octafy menyediakan OpenAI Chat Completions. Gunakan router translasi seperti Claude Code Router, lalu arahkan router tersebut ke endpoint Octafy.

json

{
  "Providers": [
    {
      "name": "octafy",
      "api_base_url": "https://api.octafy.xyz/v1/chat/completions",
      "api_key": "$OCTAFY_API_KEY",
      "models": [
        "octa/glm-5.3-flash",
        "octa/glm-5.3",
        "octa/deepseek-4.1-flash",
        "octa/kimi-k3"
      ]
    }
  ],
  "Router": {
    "default": "octafy,octa/glm-5.3-flash",
    "think": "octafy,octa/glm-5.3",
    "background": "octafy,octa/glm-5.3-flash"
  }
}

bash

export OCTAFY_API_KEY="sk_live_xxxxxxxxx"
ccr start

export ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
export ANTHROPIC_AUTH_TOKEN="local-router"
claude

Cline, Roo Code, dan tools lain

Pilih provider OpenAI Compatible, isi base URL di bawah, API key Octafy, dan model ID dari katalog. Jangan menambahkan /chat/completions secara manual pada base URL.

text

Base URL : https://api.octafy.xyz/v1
API key  : sk_live_xxxxxxxxx
Model    : octa/glm-5.3-flash

Tools: kirim definisi function di field tools; respons tool_calls diteruskan apa adanya.

Model: gunakan model yang mendukung tool calling dan reasoning sesuai kebutuhan agent.

Billing: agent biasanya mengirim konteks panjang berulang; cache hit hanya 20% harga input dan memakai 20% kuota paket.

1017: DeepSeek V4.1 Flash 1017 hanya dapat dipakai lewat paket token, bukan wallet.

Chat completions

POST/v1/chat/completions

bash

curl -X POST "https://api.octafy.xyz/v1/chat/completions" \
  -H "Authorization: Bearer $OCTAFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "octa/deepseek-chat",
    "messages": [
      {"role": "user", "content": "Jelaskan apa itu SaaS"}
    ],
    "max_tokens": 512,
    "billing_mode": "auto"
  }'

json

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "octa/deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 84,
    "total_tokens": 96,
    "cached_tokens": 0
  },
  "octafy": {
    "billing_mode": "wallet",
    "cost_idr": 696,
    "balance_idr": 99230
  }
}

Field billing_mode menerima auto (default), wallet, atau package.Mode auto memakai kuota paket aktif terlebih dahulu, lalu wallet.

Streaming

Kirim "stream": true untuk menerima SSE. Gateway meneruskan chunk dari provider dan mengirim event final berisi usage dan metadata billing.

bash

curl -N -X POST "https://api.octafy.xyz/v1/chat/completions" \
  -H "Authorization: Bearer $OCTAFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"octa/deepseek-v4.1-flash-1017","stream":true,"messages":[{"role":"user","content":"Halo"}]}'

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Halo"}}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}],"usage":{...},"octafy":{...}}
data: [DONE]

Billing tetap diselesaikan meskipun koneksi client terputus setelah provider mulai memproses. Request yang gagal di tengah stream ditandai untuk rekonsiliasi, bukan diasumsikan nol biaya.

Billing & token

Token adalah unit pemakaian model. Credit adalah saldo internal; 1 credit = Rp1. Token AI tidak pernah disamakan dengan credit.

1. Reserve

Sistem menghitung estimasi biaya maksimum dan menahan saldo. Saldo yang di-reserve tidak bisa dipakai request lain.

2. Provider

Gateway memanggil provider dengan kredensial platform. Customer tidak pernah melihat key provider.

3. Metering

Input, output, dan cached token dibaca dari respons provider.

4. Settlement

Biaya aktual dihitung dari price snapshot, reserve dilepas, selisih dikembalikan ke saldo tersedia.

text

customer_cost = ceil((prompt_tokens - cached_tokens) * input_price / 1_000_000)
              + ceil(cached_tokens * cached_price / 1_000_000)
              + ceil(completion_tokens * output_price / 1_000_000)

provider_cost = ceil(prompt_tokens * provider_input / 1_000_000)
              + ceil(completion_tokens * provider_output / 1_000_000)

margin = revenue - provider_cost

Paket token

Paket memberi kuota untuk satu atau beberapa model dan masa aktif tertentu. Saat request memakai paket, saldo wallet tidak dipotong; pendapatan paket diakui secara proporsional dari deferred revenue. Sisa kuota saat kedaluwarsa diakui sebagai breakage.

GET /v1/public/packages — katalog paket.

GET /v1/packages/mine — kuota milik customer (JWT).

POST /v1/packages/:id/purchase — buat invoice pembelian paket (JWT).

Error & rate limit

Error mengikuti bentuk {"error":{"code","message","request_id"}}.Rate limit default 60 request/menit per customer dan diatur oleh admin (1–600). Limit berlaku untuk seluruh API key dan playground.

HTTP	Code	Arti
401	unauthorized	API key tidak valid atau dicabut
402	insufficient_balance	Saldo dan kuota paket tidak cukup
402	package_quota_unavailable	Mode package dipilih tetapi kuota tidak tersedia
402	model_not_allowed	Model tidak tercakup saldo wallet atau paket aktif
403	key_spend_limit	Batas belanja bulanan API key tercapai
404	not_found	Model/endpoint tidak ditemukan
429	rate_limited	Terlalu banyak request
502	provider_error	Provider menolak atau tidak dapat dihubungi
504	provider_timeout	Provider melewati batas waktu; request ditandai rekonsiliasi

Idempotency

Untuk membuat top-up atau pembelian paket, kirim header Idempotency-Key.Key yang sama tidak akan membuat order atau kredit kedua.

Siap mencoba?

Playground tersedia di dashboard.

Buka playground