Pengaturan API kompatibel OpenAI di Cursor terlihat sederhana jika Anda hanya memikirkan tiga bidang: API key, base URL, dan nama model. Dalam praktiknya, Cursor adalah alat coding tingkat lebih tinggi dengan pemilih modelnya sendiri, pencatatan penggunaan, kontrol tim, dan jalur pembuatan prompt, jadi pengaturan yang lebih aman adalah alur verifikasi, bukan sekadar salin-tempel.
Per saat dokumentasi publik API key Cursor yang dicek pada 8 Juli 2026, Cursor mendokumentasikan Bring Your Own API Key untuk penyedia tertentu di Cursor Settings > Models. Cursor mendokumentasikan kunci OpenAI, Anthropic, Google, Azure OpenAI, dan AWS Bedrock; Cursor juga mengatakan bahwa custom API keys hanya bekerja dengan model chat, Tab completion tetap menggunakan model bawaan Cursor, dan permintaan dengan own-key masih melewati server Cursor untuk pembuatan prompt final. Dokumentasi publik tidak mendokumentasikan field base URL OpenAI-compatible arbitrer umum.
Itu penting bagi pengguna Flatkey. Flatkey memberi tim satu key, gateway kompatibel OpenAI di https://router.flatkey.ai/v1, akses model lintas penyedia, dan peninjauan penggunaan serta biaya di satu tempat. Jika build Cursor Anda, kebijakan admin, atau konfigurasi penyedia mengekspos field custom OpenAI base URL, gunakan panduan ini untuk memvalidasi pengaturannya. Jika UI Cursor Anda hanya mendukung API key milik penyedia, gunakan pemeriksaan yang sama untuk memutuskan kapan tetap memakai alur penyedia yang didokumentasikan Cursor dan memakai Flatkey di alat yang secara eksplisit mengekspos custom base URL, seperti Cline atau alur router Claude Code.
Tujuannya bukan memaksa setiap permintaan Cursor melalui gateway. Tujuannya adalah membuat setiap keputusan API kompatibel OpenAI di Cursor dapat diperiksa: siapa pemilik kuncinya, base URL mana yang benar-benar digunakan, nama model mana yang dipilih, di mana penggunaan muncul, dan bagaimana melakukan rollback.
Pengaturan API kompatibel OpenAI di Cursor: apa yang harus diverifikasi terlebih dahulu
Mulailah dengan tabel keputusan singkat sebelum mengubah pengaturan apa pun.
| Surface pengaturan | Apa yang didokumentasikan secara publik oleh Cursor | Apa yang harus Anda verifikasi di workspace Anda |
|---|---|---|
| API key penyedia | Tambahkan key di Cursor Settings > Models untuk penyedia yang didukung. | Baris penyedia mana yang sedang Anda edit, siapa pemilik key tersebut, dan apakah kebijakan tim mengizinkan BYOK. |
| Custom base URL | Dokumentasi publik Cursor yang dicek pada 8 Juli 2026 tidak mendokumentasikan jalur base URL kompatibel OpenAI arbitrer umum. | Apakah versi Cursor yang Anda instal atau konfigurasi enterprise mengekspos override base URL. |
| Nama model | Model Cursor muncul di pemilih model; ketersediaan bergantung pada paket, penyedia, dan wilayah. | Apakah nama model yang dipilih adalah model Cursor, model penyedia, atau alias model gateway. |
| Log penggunaan | Dasbor penggunaan Cursor menampilkan penggunaan, alokasi, biaya on-demand, biaya, dan pemilihan model untuk penggunaan Cursor. | Apakah sebuah permintaan juga muncul di log Flatkey, log penyedia, atau hanya penggunaan Cursor. |
| Mode privasi | Cursor mengatakan Zero Data Retention tidak berlaku ketika Anda menggunakan API key sendiri. | Apakah review keamanan Anda menerima pembuatan prompt oleh Cursor plus jalur penyedia atau gateway yang dipilih. |
Ini adalah aturan pertama dalam pengaturan API kompatibel OpenAI di Cursor: jangan anggap field API key sebagai bukti adanya jalur gateway. Field key membuktikan entri kredensial. Field base URL, log permintaan, dan catatan penggunaan membuktikan routing.
Nilai yang perlu dikumpulkan sebelum menyentuh Cursor
Masukkan nilai pengaturan ke dalam worksheet kecil. Bagikan ini dengan orang yang memiliki billing atau security, bukan hanya developer yang melakukan perubahan UI.
| Field | Contoh Flatkey | Mengapa ini penting |
|---|---|---|
| Pemilik API key | Flatkey key khusus untuk evaluasi Cursor | Memisahkan traffic IDE dari traffic aplikasi dan membuat rollback lebih rapi. |
| Base URL | https://router.flatkey.ai/v1 | Menghindari path ganda /v1/v1 dan menjaga rute tetap kompatibel OpenAI. |
| Keluarga endpoint | Chat Completions terlebih dahulu | Dokumentasi BYOK Cursor mengatakan custom API keys hanya bekerja dengan model chat. |
| Nama model | Alias katalog Flatkey saat ini yang dipilih oleh tim | Alias gateway bisa berbeda dari nama di pemilih model Cursor. |
| Test prompt | Satu prompt Agent atau chat berisiko rendah | Membuat permintaan pertama mudah ditemukan di log. |
| Pemilik penggunaan | Halaman penggunaan Cursor, penggunaan/log Flatkey, pemilik finance | Mencegah sengketa tagihan tak terduga setelah pengujian. |
| Nilai rollback | Pengaturan model/key Cursor sebelumnya | Memungkinkan tim kembali seperti semula tanpa menghapus bukti. |
Untuk uji API kompatibel OpenAI di Cursor, kesalahan yang paling umum adalah menggunakan nama tampilan model dari satu sistem di sistem lain. Nama model Cursor, ID model penyedia, dan alias rute Flatkey tidak otomatis dapat dipertukarkan. Pilih nama model dari tempat yang akan menerima permintaan.
Jalankan smoke test eksternal terlebih dahulu
Sebelum menguji di dalam Cursor, validasi nilai gateway di luar Cursor. Cuplikan ini hanya template; ganti key dan model dengan nilai dari akun dan katalog Flatkey Anda saat ini.
export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_MODEL="your-current-model-alias"
curl -sS https://router.flatkey.ai/v1/models \
-H "Authorization: Bearer $FLATKEY_API_KEY"
Gunakan respons models untuk mengonfirmasi ID atau alias model yang tepat. Lalu uji jalur chat:
curl -sS https://router.flatkey.ai/v1/chat/completions \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{
"role": "user",
"content": "Balas dengan tepat: cursor route probe ok"
}
]
}'
Simpan timestamp permintaan, nama model, status HTTP, body respons, dan objek usage jika respons menyertakannya. Bentuk Chat Completions API OpenAI dibangun di sekitar model dan messages, dan respons yang berhasil dapat mencakup penggunaan token. Endpoint models OpenAI mencantumkan model yang saat ini tersedia untuk sebuah akun. Dua fakta ini membuat smoke test ini berguna sebelum Anda melibatkan Cursor.
Jika pengujian eksternal ini gagal, jangan lanjut ke Cursor. Perbaiki key, alias model, kuota, atau family endpoint terlebih dahulu. Pengujian eksternal yang gagal tidak akan menjadi lebih mudah di-debug setelah Cursor menambahkan pemilih modelnya sendiri, pembuatan prompt, dan path request.
Konfigurasikan Cursor hanya setelah route terbukti
Sekarang buka Cursor dan periksa pengaturan aktual yang tersedia untuk akun Anda.
- Buka Cursor Settings > Models.
- Periksa apakah organisasi Anda mengizinkan personal API keys. Admin enterprise dapat membatasi penggunaan BYOK.
- Jika Anda menggunakan jalur BYOK yang didokumentasikan Cursor, pilih baris provider yang didukung Cursor dan masukkan key provider tersebut.
- Jika environment Cursor Anda menampilkan field base URL OpenAI-compatible kustom, masukkan hanya root base URL, misalnya
https://router.flatkey.ai/v1, bukan path lengkap/chat/completions. - Masukkan atau pilih nama model dari sistem penerima. Untuk Flatkey, gunakan alias model yang dikonfirmasi di katalog Flatkey atau smoke test
/v1/models. - Simpan pengaturan, lalu pilih model target di pemilih model Cursor jika Cursor menampilkannya di sana.
Di sinilah judul artikel dapat menyesatkan tim: pengaturan API kompatibel OpenAI di Cursor belum selesai ketika halaman pengaturan tersimpan. Itu baru selesai hanya ketika request yang Anda kirim dari Cursor muncul di jejak penggunaan yang diharapkan.
Daftar periksa nama model untuk routing model Cursor
Gunakan tabel ini ketika seseorang bertanya, "Nama model apa yang harus saya ketik?"
| Pertanyaan | Bukti yang baik | Jalan pintas yang buruk |
|---|---|---|
| Apakah Cursor menampilkan model di pemilihnya? | Model aktif terlihat di panel chat atau Agent. | Mengasumsikan ID provider muncul karena key sudah disimpan. |
| Apakah gateway mengetahui alias model? | /v1/models atau katalog Flatkey menampilkan alias untuk akun Anda. | Menyalin nama model pemasaran dari posting blog. |
| Apakah family endpoint cocok? | Route Chat Completions dipilih untuk traffic model chat. | Mengirim model yang hanya native melalui path OpenAI-compatible yang salah. |
| Apakah model mendukung fitur Anda? | Uji tersimpan untuk chat biasa, streaming, dan panggilan tool jika diperlukan. | Menganggap completion teks biasa sebagai bukti semua fitur. |
| Bisakah finance menemukannya nanti? | Entri usage mencakup cukup konteks route/model untuk ditinjau. | Hanya mengandalkan jawaban yang berhasil di editor. |
Untuk peluncuran API kompatibel OpenAI di Cursor, mulai dengan chat biasa. Jangan gunakan refactor codebase besar, run Agent yang berat dengan tool, atau sesi Max Mode yang panjang sebagai pengujian pertama. Buat prompt pertama cukup membosankan sehingga catatan usage menjadi hasil utama.
Verifikasi log penggunaan di tiga tempat
Setup gateway yang mengembalikan teks tetapi tidak meninggalkan jejak usage bukanlah siap produksi. Periksa tiga lapisan setelah request pertama.
| Lapisan | Apa yang diperiksa | Pemilik |
|---|---|---|
| Usage Cursor | Usage dashboard Cursor, pemilihan model, allowance, dan biaya on-demand. | Pemilik seat Cursor atau admin tim. |
| Usage/logs Flatkey | Timestamp request, key, alias model, family endpoint, penggunaan token, konteks biaya, dan error jika tersedia. | Pemilik platform atau operasi. |
| Respons provider atau gateway | Status HTTP, usage respons, field model, dan request ID atau kode error apa pun. | Developer yang melakukan smoke test. |
Detail kepemilikan yang penting adalah dokumentasi Cursor sendiri menyatakan bahwa API key Anda dikirim ke backend Cursor pada setiap request own-key untuk pembuatan prompt akhir. Itu berarti pengujian API kompatibel OpenAI di Cursor harus ditinjau sebagai jalur tool-plus-gateway, bukan sebagai panggilan lokal langsung dari laptop Anda ke provider.
Jika tim Anda mengandalkan Cursor Zero Data Retention, baca catatan privasi Cursor BYOK sebelum menggunakan key Anda sendiri. Cursor menyatakan bahwa kebijakan Zero Data Retention-nya tidak berlaku saat menggunakan API key sendiri; penanganan data mengikuti kebijakan provider yang dipilih. Jika Anda merutekan melalui Flatkey, tambahkan kebijakan Flatkey saat ini, dashboard, dan bukti retensi ke paket tinjauan yang sama.
Memecahkan masalah kegagalan base URL, key, dan model
Sebagian besar kegagalan jatuh ke dalam sejumlah kecil penyebab.
| Gejala | Penyebab yang mungkin | Perbaikan |
|---|---|---|
401 atau error autentikasi | Key salah, ada whitespace yang ikut tersalin, key dicabut, atau key tidak diizinkan untuk route tersebut. | Salin ulang key, gunakan test key khusus, lalu coba ulang curl eksternal terlebih dahulu. |
403 atau error izin | Kebijakan tim, entitlement provider, region, atau izin gateway memblokir permintaan. | Periksa kebijakan Cursor BYOK, akses akun Flatkey, dan ketersediaan provider. |
404 atau model tidak ditemukan | Nama model tidak valid untuk sistem penerima. | Gunakan model picker, /v1/models, atau katalog Flatkey saat ini sebagai sumber kebenaran. |
429 atau error kuota | Alokasi paket Cursor, kuota provider, kuota Flatkey, atau laju permintaan terlampaui. | Kurangi volume pengujian, periksa batas, dan tetapkan penanggung jawab untuk peningkatan kuota. |
| Teks kembali tetapi tidak ada log Flatkey yang muncul | Permintaan tidak diteruskan melalui Flatkey. | Periksa kembali apakah Cursor menerima custom base URL atau hanya provider key. |
| Perilaku Cursor Tab tidak berubah | Cursor mendokumentasikan bahwa custom API key hanya berfungsi dengan model chat. | Jangan gunakan penyelesaian Tab sebagai sinyal verifikasi. |
Panduan error guide OpenAI sendiri memperlakukan error autentikasi, batas laju, kuota, dan layanan yang kelebihan beban sebagai tindakan pemilik yang berbeda. Pertahankan pemisahan itu di runbook Cursor Anda. Kebijakan retry tidak akan memperbaiki nama model yang salah, dan nama model baru tidak akan memperbaiki blok kebijakan BYOK.
Kapan tidak menggunakan Flatkey untuk Cursor
Ada kalanya keputusan API kompatibel OpenAI terbaik untuk Cursor adalah berhenti.
Jangan arahkan Cursor melalui Flatkey jika build Cursor Anda saat ini tidak menampilkan override base URL dan alur kerja Anda membutuhkan endpoint custom yang benar-benar khusus. Jangan arahkan Cursor melalui Flatkey jika admin enterprise Anda telah menonaktifkan personal API key. Jangan arahkan Cursor melalui Flatkey jika tinjauan keamanan Anda bergantung pada kontrol privasi model bawaan Cursor yang tidak berlaku untuk traffic own-key.
Dalam kasus tersebut, biarkan Cursor menggunakan jalur provider yang didokumentasikan dan gunakan Flatkey pada tempat klien secara eksplisit mendukung base URL kompatibel OpenAI: SDK aplikasi, alat internal, skrip evaluasi, Cline, Open WebUI, LangChain, LlamaIndex, atau surface integrasi lainnya. Jika Anda memerlukan pola migrasi umum, mulai dengan panduan migrasi API kompatibel OpenAI. Untuk pola router coding-agent, bandingkan pengaturan router API Claude Code dan pengaturan API kompatibel OpenAI di Cline.
Daftar periksa produksi
Sebelum menyatakan pengaturan API kompatibel OpenAI di Cursor selesai, simpan bukti ini:
| Bukti | Selesai ketika |
|---|---|
| Pengaturan Cursor | Screenshot atau catatan admin menunjukkan jalur provider/key/base URL yang digunakan, dengan rahasia disembunyikan. |
| Bukti model | Nama model berasal dari model picker Cursor, katalog Flatkey, atau /v1/models, bukan tebakan. |
| Smoke test eksternal | https://router.flatkey.ai/v1/chat/completions menghasilkan respons biasa dengan model yang dipilih. |
| Bukti permintaan Cursor | Prompt kecil di Cursor menggunakan model yang dimaksud dan tidak bergantung pada penyelesaian Tab. |
| Bukti penggunaan | Bukti usage Cursor dan usage/log Flatkey disimpan dengan timestamp. |
| Peta error | Tindakan pemilik untuk 401, 403, 404, 429, dan 5xx didokumentasikan. |
| Rollback | Path model/key Cursor sebelumnya dicatat dan dapat dipulihkan tanpa menghapus log. |
Pengaturan API kompatibel OpenAI di Cursor bernilai ketika traffic alat coding diubah menjadi penggunaan model yang terkelola dan dapat ditinjau. Simpan base URL, nama model, dan bukti log penggunaan bersama-sama. Saat Anda membutuhkan satu key gateway dan satu tempat untuk meninjau traffic model, dapatkan key Flatkey, uji dulu request chat berisiko rendah, lalu lanjutkan hanya setelah log membuktikan rutenya.
