Jika aplikasi Anda sudah menggunakan OpenAI compatible API, berpindah ke Flatkey seharusnya tidak dimulai dengan penulisan ulang. Jalur yang terkendali lebih kecil: dapatkan key Flatkey, arahkan SDK yang kompatibel dengan OpenAI Anda ke https://router.flatkey.ai/v1, pilih model ID dari katalog Flatkey, lalu verifikasi permintaan pertama di log, kuota, dan penagihan sebelum Anda mengirim traffic nyata.
Itulah nilai praktis dari OpenAI compatible API. Ini memungkinkan tim mempertahankan model mental yang sama untuk permintaan umum sambil memindahkan akses provider ke balik satu gateway. Copy produk publik Flatkey dibangun di sekitar gerakan itu: satu API key, satu base URL, harga yang jelas, penagihan terpadu, dan satu dashboard untuk key, penggunaan, dan routing.
Panduan ini menunjukkan runbook migrasinya. Isinya mencakup perubahan base URL, contoh SDK, pemetaan model ID, smoke test, pengecekan endpoint, peninjauan log penggunaan, penyiapan kuota, verifikasi penagihan, dan rollback. Gunakan ini saat Anda memindahkan workflow gaya Chat Completions yang sudah ada ke Flatkey atau menstandarkan stack multi-model di balik satu endpoint OpenAI compatible API.
Jawaban Cepat: Apa Perubahan Dalam Migrasi API yang Kompatibel dengan OpenAI?
Bagi sebagian besar klien chat yang sudah kompatibel dengan OpenAI, migrasi pertama adalah perubahan konfigurasi, bukan penulisan ulang aplikasi.
| Setting | Sebelum | Dengan Flatkey |
|---|---|---|
| API key | Key khusus provider OpenAI, Gemini, DeepSeek, atau proxy | API key Flatkey |
| Base URL | Default provider atau base URL lain yang kompatibel dengan OpenAI | https://router.flatkey.ai/v1 |
| Chat endpoint | /v1/chat/completions |
/v1/chat/completions melalui Flatkey |
| Model | Model ID provider yang sudah ada | Model ID Flatkey yang dipilih dari pricing/dashboard |
| Validation | Hanya respons yang berhasil | Respons + log penggunaan + biaya + kuota + rollback |
Kata pentingnya adalah "compatible." OpenAI compatible API tidak menjamin bahwa setiap provider, model, endpoint, dan parameter berperilaku persis seperti OpenAI. Artinya, API mengikuti cukup banyak pola request dan respons OpenAI agar panggilan klien umum dapat berjalan ketika base URL, key, dan model sudah benar. Checklist migrasi Anda harus membuktikan fitur yang benar-benar digunakan aplikasi Anda.
Mengapa Titik Akhir yang Kompatibel dengan OpenAI Menjadi Lapisan Migrasi
Hasil pencarian untuk OpenAI compatible API sebagian besar berupa referensi resmi, dokumentasi provider, plugin, dokumentasi server lokal, dan pertanyaan komunitas. Itu masuk akal. Para developer bukan hanya bertanya "apa yang kompatibel?" Mereka mencoba memindahkan kode antar penyedia model tanpa mengubah setiap titik pemanggilan.
Dokumentasi Gemini dari Google menampilkan contoh library OpenAI yang menetapkan base URL yang kompatibel dengan Gemini OpenAI dan memanggil chat completions. Dokumentasi API resmi DeepSeek menampilkan contoh SDK OpenAI dengan base URL DeepSeek dan model ID seperti deepseek-chat dan deepseek-reasoner. Polanya jelas: banyak provider menemui developer di tempat SDK yang sudah mereka gunakan.
Flatkey menggunakan ide migrasi yang sama untuk tujuan yang berbeda. Alih-alih mengarahkan OpenAI compatible API milik satu provider ke satu akun provider, Flatkey memberi tim satu base URL yang kompatibel dengan OpenAI untuk akses multi-model, penagihan terpadu, dan visibilitas dashboard.
Langkah 1: Inventarisasi Klien yang Sudah Anda Miliki
Sebelum mengubah base URL, catat apa yang benar-benar digunakan aplikasi Anda saat ini. Migrasi OpenAI compatible API yang rapi dimulai dari bentuk panggilan yang aktif, bukan aplikasi contoh baru.
| Check | What To Record |
|---|---|
| SDK | Python, Node, HTTP langsung, LangChain, LiteLLM, Vercel AI SDK, atau wrapper lainnya. |
| Endpoint | Chat Completions, Responses, embeddings, images, video, atau endpoint native provider. |
| Model ID | String persis yang digunakan di production dan model fallback apa pun. |
| Message shape | System prompt, developer message, tool message, konten multimodal, atau hanya teks biasa. |
| Parameters | Streaming, temperature, max tokens, tool calls, output JSON, response format, seed, timeout, retries. |
| Observability | Di mana Anda melihat latensi, penggunaan token, request ID, error, dan biaya saat ini. |
| Rollback | Seberapa cepat Anda dapat memulihkan API key/base URL/model lama. |
Inventaris ini menjaga migrasi tetap jujur. Jika aplikasi Anda hanya mengirim pesan chat sederhana, pengujian awal Flatkey bisa tetap kecil. Jika aplikasi Anda bergantung pada streaming, tool calls, mode JSON, images, video, atau Responses API, perlakukan setiap fitur sebagai smoke test terpisah.
Langkah 2: Letakkan URL Dasar di Belakang Satu Lapisan Konfigurasi
Jangan menyebarkan base URL baru yang kompatibel dengan OpenAI ke seluruh codebase. Letakkan di satu environment variable atau satu factory SDK.
Environment variable yang direkomendasikan:
FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="replace-with-publish-day-model-id"
ROLLBACK_OPENAI_BASE_URL="https://api.openai.com/v1"
ROLLBACK_MODEL="your-previous-model-id"Menggunakan OPENAI_BASE_URL sering kali praktis karena banyak pembungkus SDK sudah mendukung konvensi tersebut. Menggunakan FLATKEY_API_KEY dan FLATKEY_MODEL menjaga kredensial baru dan pilihan model tetap eksplisit.
Di sinilah Flatkey cocok dengan intent pencarian openai compatible base url. Migrasi harus dapat ditinjau dalam satu diff: base URL, key, model, dan langkah verifikasi.
Step 3: Jalankan A Curl Smoke Test
Mulailah dengan permintaan HTTP langsung sebelum mengubah aplikasi Anda. Ini mengisolasi masalah key, base URL, endpoint, dan ID model.
Hanya template: peninjau harus menjalankan dengan key Flatkey yang valid dan ID model yang dikonfirmasi pada hari publikasi.
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 satu kalimat yang mengonfirmasi bahwa smoke test Flatkey ini berhasil."
}
]
}'Smoke test yang berguna membuktikan lebih dari sekadar 200 OK. Untuk migrasi OpenAI compatible API, periksa:
- Respons memiliki pesan assistant yang dapat digunakan.
- Nama model adalah yang memang ingin Anda uji.
- Penggunaan muncul di dashboard Flatkey atau log penggunaan.
- Jumlah token dan biaya terlihat cukup jelas untuk tinjauan penagihan.
- Pesan error dapat dipahami jika ID model atau key salah.
- Base URL dan model lama masih dapat dipulihkan dengan cepat.
Step 4: Ubah Konfigurasi Python OpenAI SDK
Jika aplikasi Python Anda sudah menggunakan OpenAI SDK, pertahankan pembuatan client secara terpusat.
Hanya template: peninjau harus mengeksekusi sebelum publikasi.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[
{
"role": "user",
"content": "Konfirmasikan bahwa permintaan OpenAI compatible API ini dirutekan melalui Flatkey.",
}
],
)
print(response.choices[0].message.content)
print(response.usage)Rincian Python yang penting adalah base_url. Dalam migrasi OpenAI compatible API yang rapi, kode aplikasi seharusnya tidak perlu tahu apakah base URL mengarah langsung ke OpenAI, endpoint yang kompatibel dengan penyedia lain, atau Flatkey. Aplikasi seharusnya memanggil client bersama dan membiarkan konfigurasi memilih rute.
Step 5: Ubah Konfigurasi Node OpenAI SDK
Untuk aplikasi Node, konfigurasi yang setara menggunakan baseURL.
Hanya template: peninjau harus mengeksekusi sebelum publikasi.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL,
messages: [
{
role: "user",
content: "Konfirmasikan bahwa permintaan OpenAI compatible API ini dirutekan melalui Flatkey.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.usage);Ini adalah pola migrasi yang sama seperti yang terlihat di seluruh dokumentasi penyedia: pertahankan SDK, setel base URL yang berbeda, berikan API key yang kompatibel, dan pilih ID model yang ada pada platform target.
Step 6: Petakan ID Model dengan Sengaja
String model adalah tempat banyak migrasi OpenAI compatible API gagal. Base URL dapat kompatibel sementara ID model tetap spesifik untuk penyedia.
Jangan berasumsi:
- Nama model lama Anda ada di Flatkey.
- Alias model dari penyedia mengarah ke versi yang sama di balik gateway.
- Setiap model yang kompatibel mendukung keluarga endpoint yang sama.
- Model yang berfungsi untuk chat juga berfungsi untuk vision, tools, images, video, atau Responses.
Sebaliknya, gunakan tabel pemetaan ini sebelum pengujian pertama di level aplikasi:
| Penggunaan Aplikasi Saat Ini | Pemeriksaan Flatkey |
|---|---|
| Text chat | Pilih model Flatkey yang mendukung endpoint chat OpenAI. |
| Streaming chat | Uji streaming secara terpisah dengan prompt dan anggaran timeout yang sama. |
| Tool/function calling | Verifikasi model dan endpoint yang dipilih mendukung bentuk tool-call yang dikirim aplikasi Anda. |
| Output JSON | Uji response_format yang tepat atau pola structured-output Anda. |
| Input vision/image | Konfirmasi model yang dipilih menerima format input gambar yang dikirim SDK Anda. |
| Responses API | Konfirmasi endpoint/model Flatkey mendukung /v1/responses untuk use case Anda. |
| Image atau video generation | Perlakukan ini sebagai migrasi endpoint terpisah, bukan migrasi chat-completions. |
Cuplikan harga Flatkey pada 11 Juni 2026 menunjukkan family endpoint untuk OpenAI chat completions, OpenAI Responses, Anthropic messages, Gemini, image generation, dan OpenAI video. Itu berguna sebagai bukti untuk peninjau, tetapi artikel tetap harus mendorong pembaca untuk mengonfirmasi model dan fitur persis yang akan mereka gunakan pada hari publikasi.
Step 7: Verifikasi Log, Kuota, Dan Penagihan
Respons API yang kompatibel dengan OpenAI yang berhasil hanyalah checkpoint pertama. Alasan bermigrasi melalui Flatkey bukan sekadar bentuk permintaan; melainkan permukaan operasional di sekitar akses model.
Setelah smoke test, verifikasi:
| Area | Yang Perlu Diperiksa |
|---|---|
| Log penggunaan | Permintaan muncul dengan timestamp, model, penggunaan token, status, dan detail error jika ada. |
| Penagihan | Biaya terlihat dan sesuai dengan model/unit harga yang diharapkan. |
| Kuota | Kuota kecil dapat ditetapkan untuk key baru atau rute pengujian sebelum peluncuran lebih luas. |
| Routing | Permintaan diarahkan melalui jalur Flatkey yang dimaksud, bukan konfigurasi direct-provider yang lama. |
| Perilaku error | Error key salah, model salah, dan parameter yang tidak didukung cukup jelas untuk tim support. |
| Rollback | Mengembalikan base URL/model sebelumnya berfungsi tanpa perubahan kode. |
Di sinilah gateway API yang kompatibel dengan OpenAI menjadi lebih berguna daripada endpoint provider mentah. Perubahan base URL seharusnya menghasilkan visibilitas yang lebih baik, bukan hanya upstream yang berbeda.
Langkah 8: Luncurkan Secara Bertahap
Jangan memindahkan semua alur kerja sekaligus. Gunakan peluncuran bertahap:
- Jalankan smoke test curl langsung.
- Jalankan satu smoke test SDK di lokal atau staging.
- Putar ulang satu set prompt kecil yang sudah dikenal dan bandingkan bentuk output.
- Aktifkan streaming atau parameter lanjutan hanya setelah panggilan dasar berhasil.
- Berikan kuota rendah pada key pengujian.
- Kirim sebagian kecil trafik non-kritis.
- Bandingkan error, latensi, penggunaan token, dan biaya.
- Tingkatkan trafik hanya setelah log dan penagihan sesuai harapan.
Alur ini menjaga janji API yang kompatibel dengan OpenAI tetap selaras dengan realitas produksi. Kompatibilitas bukan slogan; itu adalah hasil pengujian untuk panggilan yang benar-benar dikirim aplikasi Anda.
Daftar Periksa Migrasi
Gunakan ini sebagai aset halaman publikasi.
| Langkah | Selesai? | Catatan |
|---|---|---|
| SDK dan endpoint saat ini didokumentasikan | Python, Node, HTTP, wrapper, chat, responses, image, video, dll. | |
| Key Flatkey dibuat | Gunakan key pengujian terpisah jika memungkinkan. | |
| Base URL dipusatkan | https://router.flatkey.ai/v1 sebaiknya berada di konfigurasi, bukan tersebar di kode. |
|
| Model ID dipilih dari Flatkey | Konfirmasi model ID pada hari publikasi dari harga atau dashboard. | |
| Curl smoke test berhasil | Template harus diuji reviewer sebelum dipublikasikan. | |
| Smoke test SDK Python atau Node berhasil | Gunakan SDK yang benar-benar dijalankan aplikasi Anda. | |
| Fitur streaming/tool/JSON/vision diuji | Uji hanya fitur yang Anda gunakan. | |
| Log penggunaan terlihat | Konfirmasi model, status, token, dan error di dashboard. | |
| Penagihan dan unit harga ditinjau | Jangan berasumsi unit harga provider identik. | |
| Batas kuota ditetapkan | Jaga trafik migrasi tetap terbatas. | |
| Env var rollback siap | Base URL dan model lama dapat dipulihkan tanpa perubahan kode. |
Kesalahan Umum
Kesalahan migrasi API yang kompatibel dengan OpenAI yang paling umum adalah mengubah base URL dan menganggap semua detail lain identik. Hindari jebakan ini:
- Hardcode base URL Flatkey di beberapa file.
- Menyimpan ID model provider lama yang tidak dirutekan oleh Flatkey.
- Hanya menguji non-streaming padahal produksi menggunakan streaming.
- Melewatkan pengujian tool-call atau output JSON.
- Memindahkan endpoint image/video seolah-olah itu endpoint chat-completions.
- Lupa memperbarui retry, batas timeout, dan parsing error.
- Menyatakan migrasi selesai sebelum penggunaan dan penagihan terlihat.
Flatkey mengurangi kerumitan akun provider dan routing, tetapi tidak menghilangkan kebutuhan akan pengujian migrasi yang cermat.
Kapan Flatkey Cocok
Flatkey sangat cocok ketika tim Anda menginginkan satu base URL API yang kompatibel dengan OpenAI untuk akses multi-model, alih-alih akun provider, key, penagihan, dan pemeriksaan routing yang terpisah.
Gunakan Flatkey ketika:
- Aplikasi Anda sudah menggunakan SDK yang kompatibel dengan OpenAI.
- Anda ingin satu key untuk model lintas provider seperti GPT, Claude, Gemini, DeepSeek, Qwen, Seedance 2.0, dan GPT Image.
- Anda ingin penggunaan, penagihan, key, dan routing terlihat dalam satu dashboard.
- Anda ingin batas kuota sebelum trafik meningkat.
- Anda ingin perilaku pergantian model dan load balancing ditangani oleh layer gateway.
- Anda ingin jalur migrasi menjadi "ubah base URL, verifikasi model, pantau penggunaan" alih-alih "tulis ulang integrasi model."
Gunakan akun provider langsung atau proxy yang di-host sendiri saat Anda membutuhkan kontrak khusus provider, logika routing yang sepenuhnya kustom, atau kontrol gateway lokal infrastruktur.
Pertanyaan yang sering diajukan
Apakah API yang kompatibel dengan OpenAI sama dengan OpenAI?
Tidak. OpenAI compatible API mengikuti pola request dan response bergaya OpenAI untuk endpoint yang didukung, tetapi penyedia, ID model, autentikasi, dukungan fitur, harga, dan perilaku error bisa berbeda.
Apakah saya perlu mengganti SDK saya untuk menggunakan Flatkey?
Biasanya tidak untuk migrasi chat-completions yang umum. Jika SDK Anda mendukung base URL kustom, Anda sering kali bisa tetap memakai SDK dan mengubah konfigurasi. Itulah daya tarik utama dari migrasi OpenAI compatible API.
Apa base URL yang kompatibel dengan OpenAI untuk Flatkey?
Gunakan https://router.flatkey.ai/v1 sebagai base URL yang kompatibel dengan OpenAI. Untuk chat completions, endpoint lengkapnya adalah https://router.flatkey.ai/v1/chat/completions.
Bisakah saya tetap memakai nama model yang sudah ada?
Hanya jika ID model tersebut tersedia dan didukung melalui Flatkey. Periksa pricing atau dashboard, lalu uji ID model yang persis sama sebelum peluncuran.
Haruskah saya migrasi Chat Completions atau Responses terlebih dahulu?
Migrasikan endpoint yang digunakan aplikasi Anda saat ini. Aplikasi Chat Completions yang sudah ada dapat mulai dengan /v1/chat/completions. Jika aplikasi Anda menggunakan Responses API, uji /v1/responses secara terpisah dan pastikan model yang dipilih mendukung fitur yang Anda butuhkan.
Bagaimana cara melakukan rollback?
Simpan base URL lama, API key, dan model di konfigurasi sampai log, biaya, kuota, dan perilaku aplikasi Flatkey terverifikasi. Rollback seharusnya berupa perubahan variabel lingkungan, bukan penulisan ulang kode.
Dapatkan Kunci
Jika Anda sudah memiliki aplikasi yang dibangun di atas OpenAI compatible API, Flatkey membuat migrasinya tetap kecil: dapatkan kunci, ubah base URL, pilih model, jalankan smoke test, dan pantau penggunaan dalam satu dashboard.
Dapatkan kunci, lalu gunakan https://router.flatkey.ai/v1 sebagai base URL untuk tes migrasi Flatkey pertama Anda.
