Checklist Migrasi ke API Kompatibel OpenAI

API kompatibel OpenAI menerima request yang sama dengan API OpenAI dan mengembalikan bentuk respons yang sama. Itulah yang membuat migrasi murah: SDK, prompt, definisi tool, dan kode parsing Anda tetap seperti semula. Yang berubah adalah tujuan request, key yang mengautentikasinya, dan nama model yang Anda minta.

Panduan ini memakai migrasi ke zcloud sebagai contoh konkret, tetapi checklist-nya berlaku untuk penyedia kompatibel OpenAI mana pun.

1. Inventarisasi apa yang benar-benar dipanggil kode Anda

Sebelum mengubah apa pun, catat endpoint dan fitur yang Anda pakai. Cari pemanggilan SDK dan request HTTP mentah di codebase, lalu catat:

• Endpoint — chat completions, Responses API, embeddings, gambar, audio, file, batch.
• Fitur — streaming, tool calling, structured output, input gambar, prompt caching.
• Model — setiap nama model yang ditulis langsung di konfigurasi, environment variable, atau kode.

Kompatibilitas berlaku per endpoint. zcloud melayani POST /v1/chat/completions, POST /v1/responses, dan GET /v1/models dalam format OpenAI, plus POST /v1/messages dalam format Anthropic, semuanya dengan satu API key. Jika Anda bergantung pada endpoint yang tidak dicantumkan penyedia, biarkan trafik itu di tempat semula.

2. Ganti base URL dan key

SDK resmi OpenAI untuk Python dan Node membaca dua environment variable, sehingga banyak proyek bisa migrasi tanpa menyentuh kode:

OPENAI_BASE_URL=https://api.zrouter.dev/v1
OPENAI_API_KEY=zr_your_key_here

Jika kode Anda membuat client secara eksplisit, berikan nilai yang sama:

from openai import OpenAI

client = OpenAI(base_url="https://api.zrouter.dev/v1", api_key="zr_your_key_here")

Perhatikan akhiran /v1: client format OpenAI mengharapkannya ada di base URL. SDK Anthropic adalah pengecualian — ia memakai root URL (https://api.zrouter.dev) dan menambahkan /v1/messages sendiri. Key dibuat di dashboard dan hanya ditampilkan sekali, jadi simpan di secret manager, bukan di source control.

3. Petakan nama model

Langkah inilah yang paling sering salah. Nama model bersifat spesifik penyedia: nama yang dikirim kode Anda harus sama persis dengan katalog penyedia. Ambil daftar yang bisa dipakai key Anda:

curl https://api.zrouter.dev/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Lalu ganti setiap nama yang ditulis langsung dengan entri yang sesuai. Simpan nama model di konfigurasi, bukan di kode, agar perubahan berikutnya cukup mengedit konfigurasi. Katalog model publik menampilkan nama yang sama beserta harganya.

4. Uji ulang streaming dan tool call

Streaming memakai server-sent events dengan format yang sama seperti API aslinya, jadi helper streaming di SDK tetap berfungsi. Tetap jalankan jalur streaming nyata Anda dari ujung ke ujung: pastikan chunk terakhir tiba, usage dilaporkan di tempat Anda membacanya, dan pembatalan dari client menghentikan request.

Untuk tool calling dan structured output, putar ulang beberapa request produksi nyata ke endpoint baru dan bandingkan hasil parsing-nya. Bentuk request yang sama tidak menjamin setiap model berperilaku identik, terutama jika Anda juga mengganti model.

5. Perbarui penanganan error

API kompatibel memakai ulang envelope error OpenAI, tetapi penyedia menambahkan kode sendiri. Di zcloud, yang perlu ditangani secara eksplisit adalah:

• 401 invalid_api_key — key salah, dicabut, atau kedaluwarsa. Jangan retry.
• 402 insufficient_balance — tidak ada kuota Token Plan atau saldo PAYG untuk request itu. Retry tidak membantu; isi saldo dulu.
• 404 model_not_found — nama model tidak ada di katalog.
• 429 dan 5xx — sementara; retry dengan exponential backoff dan jitter.

Tabel lengkapnya ada di referensi error.

6. Periksa billing sebelum beralih

Pahami cara Anda ditagih sebelum trafik produksi datang. Di zcloud, request ditagih setelah berhasil, sesuai tarif per token model. Jika Anda punya Token Plan untuk model tersebut, kuotanya dipakai lebih dulu dan saldo PAYG menutup sisanya. Kirim beberapa request uji, lalu pastikan pemakaian yang tercatat di dashboard sesuai perkiraan Anda. Halaman harga menampilkan tarif setiap model di samping harga resmi.

7. Rilis bertahap

Arahkan sebagian kecil trafik ke base URL baru lebih dulu — feature flag atau variabel per environment sudah cukup. Bandingkan latensi, tingkat error, dan kualitas output dengan penyedia lama selama beberapa hari, lalu pindahkan sisanya. Simpan konfigurasi lama agar rollback cukup dengan mengubah satu baris.

Checklist migrasi

• Semua endpoint dan fitur yang Anda pakai dilayani penyedia baru.
• OPENAI_BASE_URL berakhiran /v1; key disimpan sebagai secret.
• Setiap nama model sama persis dengan GET /v1/models.
• Streaming, tool call, dan structured output lolos uji replay.
• Error 401, 402, 404, dan error yang bisa di-retry sudah ditangani.
• Pemakaian uji di dashboard sesuai perkiraan biaya Anda.
• Rollback cukup dengan perubahan konfigurasi.

Untuk referensi endpoint lengkap dan contoh siap salin, lihat quickstart API kompatibel OpenAI. Untuk memperkirakan penghematannya, ikuti cara menghitung biaya API LLM.

FAQ

Apakah saya perlu menulis ulang kode? Biasanya tidak. Jika Anda memakai SDK resmi OpenAI, mengganti base URL, API key, dan nama model umumnya sudah cukup.

Bisakah saya memakai SDK Anthropic dengan key yang sama? Bisa. zcloud melayani endpoint messages Anthropic dengan key yang sama; arahkan SDK Anthropic ke root URL tanpa /v1.

Apa yang terjadi jika saldo saya habis? API mengembalikan 402 insufficient_balance dan request tidak dijalankan, sehingga tidak ada biaya untuk request itu.