API kompatibel OpenAI: mengganti Base URL

API yang kompatibel dengan OpenAI memungkinkan klien lama mempertahankan header autentikasi, bentuk JSON, dan pola streaming yang sudah dikenal, meskipun trafik dialihkan ke gateway lain. Perubahannya bisa sesederhana mengganti Base URL dan kunci API. Namun, kompatibilitas tetap merupakan kontrak protokol—bukan jaminan bahwa setiap model mendukung semua endpoint atau kolom khusus penyedia.

Panduan ini membahas jalur migrasi yang aman untuk aplikasi, skrip, dan alat AI yang sudah menggunakan API bergaya OpenAI.

Cakupan sebenarnya dari kompatibilitas OpenAI

Bagian kontrak yang umumnya dapat digunakan kembali meliputi:

• autentikasi token Bearer melalui header Authorization;
• permintaan dan respons JSON pada endpoint /v1 yang memiliki versi;
• endpoint umum seperti /v1/models, /v1/chat/completions, dan /v1/responses;
• Server-Sent Events untuk permintaan streaming yang didukung;
• kolom yang sudah dikenal seperti model, messages, input, stream, serta definisi alat yang didukung protokol terpilih.

Kompatibilitas bukan berarti satu model dapat dipindahkan bebas antara Chat Completions dan Responses. Sebuah model mungkin hanya tersedia melalui salah satu protokol yang telah diverifikasi. Kolom penalaran, pencarian, atau input multimodal khusus penyedia juga mungkin harus diteruskan apa adanya, bukan diterjemahkan oleh gateway.

Gunakan katalog langsung Model & Harga sebagai sumber acuan untuk model, grup, dan format API yang akan dipakai.

Menyiapkan migrasi

Sebelum mengubah kode aplikasi:

1. Buat kunci khusus di Kunci API; jangan menggunakan kembali kunci pribadi atau milik integrasi lain.
2. Pilih grup utama yang benar-benar dapat mengakses model tujuan.
3. Tambahkan grup cadangan dalam urutan yang jelas, hanya jika grup tersebut mendukung model yang sama serta sesuai dengan kebijakan biaya dan keandalan.
4. Catat endpoint saat ini, ID model persis, pengaturan streaming, dan penggunaan alat agar perilaku sebelum dan sesudah migrasi dapat dibandingkan.

Base URL baku untuk API Modelflare yang kompatibel dengan OpenAI adalah:

https://modelflare.dev/v1

Sebagian besar SDK mengharapkan Base URL berakhir di /v1, lalu menambahkan /chat/completions atau /responses sendiri. Periksa dokumentasi klien agar jalur endpoint tidak terduplikasi.

Verifikasi autentikasi dan akses model terlebih dahulu

Simpan kunci di variabel lingkungan, bukan di kode sumber:

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

Setelah itu, pastikan kunci dapat menampilkan model yang tersedia:

curl -sS https://modelflare.dev/v1/models \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

Respons yang berhasil membuktikan bahwa domain, koneksi TLS, dan kunci valid. Hal itu belum membuktikan setiap model menerima semua format permintaan, sehingga pengujian berikutnya harus menggunakan endpoint yang benar-benar akan dipakai.

Kirim satu permintaan dengan protokol tujuan

Untuk model yang dinyatakan mendukung Chat Completions:

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "user", "content": "Jawab dengan nama model yang sedang aktif."}
    ],
    "stream": false
  }'

Untuk model pemrograman yang mendukung Responses:

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Jawab dengan nama model yang sedang aktif.",
    "stream": false
  }'

Gunakan ID model persis seperti yang terlihat di katalog. Hasil model_not_found biasanya berarti kunci atau grup tidak memiliki akses; mengubah huruf besar-kecil umumnya tidak menyelesaikan masalah.

Uji streaming secara terpisah

Keberhasilan permintaan non-streaming belum cukup jika aplikasi membutuhkan keluaran bertahap. Ulangi dengan "stream": true, pastikan event tiba sedikit demi sedikit, dan periksa bahwa klien tidak menahan seluruh respons sebelum menampilkannya.

Saat mendiagnosis streaming yang lambat, pisahkan:

• waktu untuk autentikasi dan pemilihan rute;
• waktu menunggu header respons upstream;
• waktu sampai teks, penalaran, atau event alat efektif pertama;
• laju generasi setelah keluaran mulai terlihat.

Log penggunaan Modelflare menyimpan metrik waktu per permintaan tanpa menyimpan prompt, teks respons, body mentah, kunci API, alamat email, atau alamat IP dalam bentuk teks biasa.

Daftar periksa sebelum produksi

• Simpan kunci API di penyimpanan rahasia atau variabel lingkungan.
• Tetapkan Base URL ke https://modelflare.dev/v1.
• Gunakan model yang secara eksplisit mendukung endpoint pilihan.
• Uji mode streaming dan non-streaming secara terpisah.
• Jika digunakan, uji alat, keluaran terstruktur, kontrol penalaran, dan input multimodal.
• Pertahankan nilai eksplisit 0 dan false jika memiliki arti.
• Atur timeout sesuai beban kerja nyata, bukan prompt pemeriksaan yang sangat singkat.
• Setelah peralihan, tinjau status, latensi, token, grup terpilih, dan biaya di log penggunaan.

Setelah batas protokol terverifikasi, klien biasanya dapat mempertahankan siklus permintaannya. Di balik endpoint yang sama, Modelflare menangani akses model, kebijakan perutean, dan visibilitas setiap permintaan.