Self-host New API: satu gateway untuk Claude, OpenAI, dan Gemini, dipakai oleh Claude Code dan Codex

Satu rekan tim memakai Claude Code, yang lain memakai Codex CLI, dan ada lagi yang mengobrol di Open WebUI. Setiap alat menyimpan salinan kunci penyedianya sendiri, penggunaan tercatat di tagihan yang terpisah-pisah, dan tidak ada yang bisa memastikan siapa memakai apa atau kunci mana yang harus dicabut.

New API adalah gateway model open source. Anda menaruh kunci OpenAI, Anthropic, Gemini, dan penyedia lainnya di baliknya, lalu memberi setiap orang atau alat sebuah kunci yang diterbitkan New API, lengkap dengan model dan kuotanya sendiri. New API melayani format OpenAI Chat Completions, Responses, Anthropic Messages, dan Gemini, sehingga alat coding yang umum dapat langsung terhubung.

Panduan ini memakai template New API dari Zenavo untuk menjalankan gateway di server yang Anda sewa atau miliki. Server, Zenavo, dan API model upstream ditagih secara terpisah; New API meneruskan dan mengukur permintaan, bukan membuat panggilan model menjadi lebih murah. New API berfokus pada pembagian kunci dan kuota per anggota tim; jika Anda terutama membutuhkan translasi protokol dan failover untuk agen coding sendiri (Claude Code dan Codex), lihat juga gateway Magpie yang lebih ringan.

Deploy New API

Hubungkan server Linux ke Zenavo, buka template New API, pilih server, lalu deploy.

Saat ini template menyiapkan:

Pengaturan	Nilai atau fungsi
Image	calciumion/new-api:latest
Port HTTP	3000
Volume	/data, berisi database SQLite bawaan dan log
SESSION_SECRET	Dibuat saat proyek dibuat; menandatangani sesi login
TZ	UTC; ubah ke zona waktu Anda jika mau

latest mengikuti upstream. Untuk pemakaian jangka panjang, tetapkan tag yang sudah Anda uji di Source pada Settings layanan, lalu catat tag tersebut.

Tambahkan domain dan langsung selesaikan penyiapan

Di tab Networking pada layanan new-api, pasang domain seperti ai.example.com ke port 3000, tambahkan record A yang mengarah ke server, lalu tunggu HTTPS aktif. Lihat Domain & HTTPS.

Kunjungan pertama membuka wizard penyiapan New API, tempat Anda membuat akun admin. Begitu gateway menyimpan kunci penyedia, ia bisa menghabiskan uang, jadi selesaikan penyiapan sendiri segera setelah domain berfungsi, lalu periksa di pengaturan sistem apakah pengguna baru boleh mendaftar sendiri. Untuk Anda dan tim, matikan pendaftaran publik dan buat akun sebagai admin.

Tambahkan channel untuk penyedia Anda

New API menyebut setiap koneksi upstream sebagai channel. Di halaman Channels, tambahkan satu: pilih jenis penyedia, masukkan kunci API penyedia tersebut dan model yang ingin ditawarkan, simpan, lalu klik Test untuk melihat respons.

Beberapa tips:

• Masukkan kunci penyedia hanya di channel, jangan pernah di variabel Zenavo, tangkapan layar, atau obrolan.
• Beri nama channel yang jelas, seperti "Anthropic resmi", agar log mudah dibaca dan channel mudah dinonaktifkan.
• Tawarkan hanya model yang Anda perlukan. Model yang ada di daftar belum tentu boleh dipanggil oleh akun penyedia Anda.
• Gunakan kunci API resmi dari penyedia dan patuhi ketentuannya. Jangan menjual kembali atau membagikan langganan chat pribadi sebagai API.

Bagikan kunci dan kuota

Di halaman Tokens, buat kunci untuk setiap orang atau alat, beserta model, kuota, dan masa berlakunya. Kunci sk- ini diterbitkan oleh New API: jika bocor, hapus di sini, tanpa perlu merotasi kunci penyedia.

Terbitkan kunci per orang dan per alat, misalnya "Alex – Claude Code" dan "Alex – Open WebUI". Penggunaan jadi mudah dibaca, dan mencabut satu kunci tidak mengganggu yang lain.

Hubungkan Claude Code

Claude Code dapat mengirim permintaannya ke endpoint Anthropic Messages kustom melalui variabel lingkungan. Di komputer Anda:

export ANTHROPIC_BASE_URL="https://ai.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-token-new-api-anda"
claude

Isi ANTHROPIC_BASE_URL hanya dengan domain, tanpa /v1: Claude Code menambahkan /v1/messages sendiri. Jika nama model yang diminta Claude Code berbeda dari nama di channel, petakan di channel New API, atau pilih model yang ditawarkan gateway dengan /model di Claude Code. Jika Anda juga ingin memeriksa log, men-deploy, dan melakukan rollback layanan Zenavo langsung dari Claude Code dengan MCP dan Skills, lihat Deploy dan debug proyek Zenavo dari Claude Code.

Hubungkan Codex CLI

Codex CLI mendefinisikan provider kustom di ~/.codex/config.toml. Ganti model dengan salah satu yang ditawarkan channel Anda:

model = "model-yang-ditawarkan-channel-anda"
model_provider = "newapi"

[model_providers.newapi]
name = "New API"
base_url = "https://ai.example.com/v1"
env_key = "NEWAPI_API_KEY"
wire_api = "responses"

Lalu jalankan export NEWAPI_API_KEY="sk-…" dan mulai codex. Berbeda dengan Claude Code, base_url di sini menyertakan /v1.

Hubungkan Open WebUI dan LobeHub

Jika Anda menjalankan Open WebUI, buka Settings → Admin → Connections dan tambahkan koneksi yang kompatibel dengan OpenAI: Base URL https://ai.example.com/v1, dan sebagai kunci API, token yang dibuat khusus untuk Open WebUI. Jika Anda menjalankan LobeHub, arahkan pengaturan provider atau OPENAI_PROXY_URL ke https://ai.example.com/v1 dengan cara yang sama.

Jika keduanya berada di proyek Zenavo yang sama (tambahkan New API ke proyek Open WebUI lewat Add Service → Templates), gunakan jaringan privat sebagai gantinya: http://new-api.zenavo.internal:3000/v1. Permintaan pun tidak pernah keluar dari server; lihat Jaringan Privat.

Backup dan upgrade

New API menyimpan akun, channel, dan token di volume /data, termasuk kunci penyedia Anda, jadi jaga backup-nya seketat kunci itu sendiri.

Pada jendela pemeliharaan, hentikan proyek, cadangkan volume dari tab Backup & Restore pada layanan new-api, jalankan kembali proyek, lalu unduh salinannya untuk disimpan. Sebelum upgrade, baca catatan rilis dan buat backup terlebih dahulu. Jika upgrade mengubah skema database, kembali ke image lama mungkin tidak membatalkannya; pulihkan backup dari sebelum upgrade sebagai gantinya.

Pertanyaan umum

Claude Code mengembalikan 404 atau tidak bisa terhubung? Pastikan ANTHROPIC_BASE_URL tidak diakhiri dengan /v1, lalu lihat log New API untuk mengetahui apakah permintaan sampai dan model apa yang diminta.

Codex mengatakan modelnya tidak ada? model di config.toml harus ditawarkan oleh sebuah channel dan diizinkan untuk token tersebut. Pastikan juga wire_api bernilai responses.

Apakah New API menyimpan percakapan? New API mencatat panggilan dan penggunaan; kolom apa saja yang dicatat bergantung pada versi dan pengaturannya. Permintaan tetap dikirim ke penyedia upstream: menjalankan gateway di server Anda tidak membuat datanya tetap berada di server itu.

Apakah server kecil sudah cukup? New API sendiri ringan; bebannya berasal dari permintaan yang berjalan bersamaan. Jika banyak orang men-stream jawaban panjang sekaligus, pantau memori dan bandwidth server.

Mulailah dari template New API: selesaikan penyiapan dan matikan pendaftaran publik terlebih dahulu, lalu tambahkan channel, terbitkan token, dan arahkan alat coding Anda ke sana.