API yang Kompatibel dengan OpenAI: Checklist Migrasi untuk Developer
Oleh Nicho
API yang kompatibel dengan OpenAI bisa membuatmu tetap memakai library klien yang sudah ada sambil mengganti layanan di belakangnya. Itu berguna untuk mengevaluasi model, mengendalikan biaya, atau menggabungkan penyedia. Tapi itu tidak menjamin setiap endpoint, parameter, atau fitur aplikasi akan berperilaku sama persis.
Migrasi yang aman dimulai dari permintaan yang benar-benar dilakukan aplikasimu. Anggap kompatibilitas sebagai daftar periksa untuk model dan rute tertentu, bukan label yang ditempelkan ke seluruh platform.
Panduan ini memakai konfigurasi cheapaimodel sebagai contoh konkret. Contohnya mengikuti dokumentasi publik yang ditinjau pada 26 Oktober 2026; itu bukan hasil uji API yang terautentikasi.
1. Pisahkan empat jenis kompatibilitas
| Lapisan | Pertanyaan yang harus dijawab | Bukti yang perlu dikumpulkan |
|---|---|---|
| Klien | Bisakah SDK mengirim permintaan ke layanan ini? | Base URL kustom dan metode autentikasi yang terdokumentasi |
| Protokol | Apakah server memahami bentuk permintaannya? | Dokumentasi endpoint dan parameter |
| Model | Apakah model yang dipilih mengimplementasikan fiturnya? | Daftar kemampuan khusus model dan uji yang terarah |
| Aplikasi | Apakah hasilnya memenuhi alur kerjamu? | Kasus regresi, output yang tervalidasi, dan metrik operasional |
Satu completion teks yang berhasil hanya menjawab sebagian kecil dari daftar periksa ini. Itu tidak membuktikan bahwa input gambar, tool call, output terstruktur, atau status percakapan akan berfungsi.
Tuliskan kemampuan yang dibutuhkan aplikasimu sebelum memilih pengganti. Pisahkan fitur wajib dari sekadar kemudahan. Kalau tidak, uji coba teks murah bisa menyembunyikan celah integrasi yang mahal.
2. Konfigurasikan key, base URL, dan model secara bersamaan
cheapaimodel mendokumentasikan https://api.cheapaimodel.ai/v1 sebagai base URL OpenAI SDK-nya. Masukkan API key gateway, bukan key penyedia lain yang tidak terkait. Hindari menaruh /chat/completions di base URL karena SDK menambahkan path resource-nya. Domain situs web bukan host API. Lihat panduan base URL.
Konfigurasi minimalnya seperti ini:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["CHEAPAIMODEL_API_KEY"],
base_url="https://api.cheapaimodel.ai/v1",
)
result = client.chat.completions.create(
model="deepseek-v4-1-flash",
messages=[{"role": "user", "content": "Reply with one short greeting."}],
)
print(result.choices[0].message.content)
ID model mengikuti panduan SDK gateway; setiap halaman model mencantumkan ID dan harganya, misalnya DeepSeek V4.1 Flash. Jangan berasumsi penyedia lain memakai ID yang sama untuk keluarga model yang sama. Simpan ketiga nilai konfigurasi ini bersama-sama di pengaturan deployment-mu supaya perubahan sebagian tidak tanpa sengaja mengirim key baru ke endpoint lama.
Jauhkan key dari bundle frontend, file yang di-commit, dan log debug. Pakai key terpisah untuk lingkungan migrasi supaya kamu bisa mencabutnya secara independen.
3. Kenali Chat Completions versus Responses
Periksa metode SDK yang dipanggil aplikasimu. client.chat.completions.create(...) dan client.responses.create(...) adalah antarmuka yang berbeda. Pengaturan yang disebut "kompatibel dengan OpenAI" di sebuah aplikasi bisa memakai salah satunya.
cheapaimodel mencantumkan kedua rute, tapi dokumentasinya menyatakan endpoint yang didukung bergantung pada model. Verifikasi kombinasi rute/model daripada berasumsi ketersediaan salah satunya berarti yang lain juga tersedia. Lihat referensi API dan FAQ.
Untuk setiap rute, catat:
- Kolom permintaan yang dikirim aplikasimu.
- Kolom respons yang dibacanya.
- Bagaimana ia meneruskan riwayat percakapan atau state.
- Alat atau opsi pemformatan apa yang dibutuhkannya.
- Bagaimana parser streaming-nya mengenali penyelesaian.
Jangan ubah endpoint dan parser respons secara terpisah. Migrasi belum selesai kalau generasi berhasil tapi aplikasi membaca kolom yang salah dan menampilkan jawaban kosong.
4. Audit parameter, jangan teruskan semuanya
Buat inventaris kecil dari permintaan representatif dengan kredensial dan konten pribadi dihapus. Sertakan kolom opsional yang ditambahkan framework, bukan hanya kolom yang terlihat di kodemu sendiri.
Uji batas token, kontrol reasoning, opsi sampling, tools, dan pemformatan output secara terpisah. Parameter yang diterima belum tentu parameter yang efektif. Referensi Chat Completions DeepSeek saat ini mendokumentasikan pengaturan yang perilakunya bergantung pada mode thinking, bersama kolom usang yang tidak lagi berpengaruh.
Structured output layak diuji sendiri. OpenAI membedakan JSON mode dari Structured Outputs yang dibatasi skema. Permintaan berbentuk OpenAI tidak memindahkan jaminan itu ke setiap server yang kompatibel. Verifikasi dukungan format yang didokumentasikan penyedia terpilih, lalu validasi hasilnya di aplikasimu. Lihat panduan structured output OpenAI.
5. Uji jalur kegagalan dan perilaku streaming
Gunakan rangkaian regresi yang ringkas, bukan satu prompt yang mengesankan:
| Kasus | Pengamatan yang diperlukan |
|---|---|
| Permintaan teks pendek | Konten yang bisa dipakai sampai ke aplikasi |
| Percakapan multi-turn | Konteks sebelumnya yang relevan tetap terjaga |
| Respons streaming | Delta tersusun dengan benar dan interupsi terlihat |
| Alur tool, jika diperlukan | Argumen tervalidasi sebelum eksekusi |
| Respons terstruktur, jika diperlukan | Output tidak valid atau tidak lengkap ditolak |
| Model atau key tidak valid | Error yang bisa dibaca sampai ke operator |
| Permintaan lambat atau terputus | Perilaku batas waktu dan retry terbatas |
Jalankan ini di lingkungan non-produksi dengan batas pengeluaran yang jelas. Catat request ID jika tersedia, status HTTP, latensi, status akhir, dan hasil validasi. Jangan pernah mencatat kredensial. Sembunyikan konten pelanggan kecuali kebijakan logging-mu secara eksplisit mengizinkannya.
6. Pisahkan protokol dan layanan lain
Kompatibilitas Anthropic Messages adalah kontrak integrasi tersendiri. Itu tidak bisa disimpulkan dari kompatibilitas OpenAI. cheapaimodel mendokumentasikan konvensi Base URL yang berbeda untuk SDK Anthropic, yang menambahkan path /v1/messages-nya sendiri. Ikuti konfigurasi yang didokumentasikan daripada memakai ulang URL begitu saja.
Audit juga embeddings, penyimpanan, pemrosesan batch, dan tool yang dihosting secara terpisah. Override Base URL global bisa mengalihkan lebih banyak klien dari yang dimaksud. Utamakan konfigurasi per klien yang eksplisit kalau aplikasimu memakai beberapa layanan.
7. Luncurkan dengan keputusan yang bisa dibalik
Mulai dari traffic internal atau beban kerja yang sempit. Bandingkan keberhasilan tugas dan biaya per hasil yang diterima, bukan hanya harga token. Perbandingan harga LLM API kami memberi titik awal untuk sisi harga; suite regresi kamu menyediakan bukti kualitasnya.
Simpan konfigurasi sebelumnya, tentukan ambang rollback, dan hindari peralihan penyedia otomatis untuk alur kerja yang punya efek samping sampai eksekusi ganda bisa dikendalikan.
Migrasi siap kalau fitur yang dibutuhkan lolos, kegagalan tetap bisa dipahami, dan aplikasi bisa kembali ke konfigurasi sebelumnya dengan aman. Memakai ulang SDK adalah awal dari proses itu, bukan kriteria penerimaannya.