Panduan API kompatibel OpenAI: ganti Base URL

Pelajari cakupan kompatibilitas OpenAI, cara memindahkan klien yang sudah ada ke Modelflare, dan batas yang perlu diverifikasi sebelum traffic produksi.

Panduan API kompatibel OpenAI: ganti Base URL

API yang kompatibel dengan OpenAI memungkinkan klien yang sudah ada tetap memakai header autentikasi, bentuk permintaan JSON, dan pola streaming yang sudah dikenal, sambil mengirim traffic ke gateway lain. Perubahannya bisa sesederhana mengganti Base URL dan kunci API, tetapi kompatibilitas tetap merupakan kontrak protokol—bukan janji bahwa setiap model mendukung setiap endpoint atau kolom khusus penyedia.

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

Cakupan sebenarnya dari kompatibilitas OpenAI

Bagian kontrak yang paling dapat digunakan kembali adalah:

  • Autentikasi token Bearer melalui header Authorization.
  • Permintaan dan respons JSON pada endpoint /v1 yang berversi.
  • Endpoint umum seperti /v1/models, /v1/chat/completions, dan /v1/responses.
  • Server-sent events untuk permintaan streaming yang didukung.
  • Kolom permintaan yang sudah dikenal seperti model, messages, input, stream, serta definisi alat jika protokol yang dipilih mendukungnya.

Kompatibilitas tidak berarti satu model dapat dipindahkan secara bebas antara Chat Completions dan Responses. Sebuah model mungkin hanya tersedia melalui satu protokol yang telah diverifikasi. Kolom penalaran, pencarian, atau multimodal khusus penyedia juga mungkin perlu diteruskan apa adanya (raw pass-through), bukan diterjemahkan di sisi gateway.

Jadikan katalog Model & Harga yang aktif sebagai sumber acuan untuk model, grup, dan format API yang akan Anda gunakan.

Menyiapkan migrasi

Sebelum mengubah kode aplikasi:

  1. Buat kunci khusus di Kunci API, jangan menggunakan kembali kunci pribadi atau kunci integrasi lain yang tidak berkaitan.
  2. Pilih grup model utama yang dapat mengakses model yang dituju.
  3. Tambahkan grup cadangan berurutan hanya jika grup tersebut juga mendukung model itu serta sesuai dengan kebijakan biaya dan keandalan yang sama.
  4. Catat endpoint, ID model, pengaturan streaming, dan penggunaan alat saat ini agar perilaku sebelum dan sesudah migrasi dapat dibandingkan.

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

https://modelflare.dev/v1

Sebagian besar SDK mengharapkan Base URL berakhir di /v1, lalu menambahkan sendiri /chat/completions atau /responses. Periksa dokumentasi klien sebelum menambahkan akhiran endpoint kedua.

Verifikasi autentikasi dan akses model terlebih dahulu

Simpan kunci di variabel lingkungan, bukan di kode sumber:

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

Lalu pastikan kunci tersebut dapat menampilkan daftar model yang tersedia:

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

Respons yang berhasil membuktikan bahwa hostname, jalur TLS, dan kunci sudah valid. Namun, respons itu belum membuktikan bahwa format permintaan tertentu valid untuk setiap model yang dikembalikan, sehingga pemeriksaan berikutnya harus menggunakan endpoint yang dituju.

Kirim satu permintaan dengan protokol yang dituju

Untuk model Chat Completions yang tercantum kompatibel dengan format tersebut:

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": "Reply with the active model name."}
    ],
    "stream": false
  }'

Untuk model coding yang kompatibel dengan 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": "Reply with the active model name.",
    "stream": false
  }'

Gunakan ID model persis seperti yang tercantum di katalog aktif. Hasil model_not_found biasanya berarti kunci atau grup yang dipilih tidak dapat mengakses model tersebut, bukan masalah yang dapat diperbaiki dengan mengubah huruf besar-kecil.

Uji streaming secara terpisah

Keberhasilan non-streaming belum cukup untuk aplikasi yang bergantung pada streaming. Ulangi permintaan dengan "stream": true, pastikan event tiba secara bertahap, dan pastikan klien tidak menahan (buffer) seluruh respons sebelum menampilkannya.

Saat mendiagnosis stream yang lambat, pisahkan:

  • waktu untuk autentikasi dan pemilihan rute;
  • waktu hingga header respons dari penyedia layanan diterima;
  • waktu hingga konten efektif atau delta alat pertama;
  • throughput generasi setelah output yang terlihat mulai muncul.

Untuk keperluan ini, log penggunaan Modelflare menyimpan metadata waktu per permintaan tanpa menyimpan prompt, teks respons, isi permintaan mentah, kunci API, email, atau alamat IP dalam bentuk teks biasa.

Daftar periksa migrasi 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 yang dipilih.
  • Uji mode non-streaming dan streaming secara terpisah.
  • Uji alat, output terstruktur, kontrol penalaran, dan input multimodal jika aplikasi menggunakannya.
  • Pertahankan nilai nol atau false yang eksplisit jika nilai tersebut bermakna dalam permintaan klien.
  • Atur batas waktu klien sesuai beban kerja nyata, bukan prompt pemeriksaan kesehatan yang singkat.
  • Setelah peralihan, tinjau status, latensi, penggunaan token, grup yang dipilih, dan biaya di log penggunaan.

Setelah batas protokol terverifikasi, klien biasanya dapat mempertahankan siklus permintaan yang sudah ada, sementara Modelflare menyediakan akses model, kebijakan perutean, dan visibilitas per permintaan di balik endpoint yang kompatibel.

Untuk lapisan operasional di balik endpoint tersebut, baca Apa itu gateway API AI?. Jika klien dapat menggunakan lebih dari satu format OpenAI, bandingkan Responses API vs. Chat Completions sebelum mengubah path.