Base URL Kompatibilitas Gemini API OpenAI dan Pengaturan Router Flatkey

Jika Anda mencoba menggunakan Gemini dengan klien yang kompatibel dengan OpenAI, detail yang paling penting adalah base URL.

Untuk akses langsung ke Google Gemini API, base URL resmi yang kompatibel dengan OpenAI adalah:

https://generativelanguage.googleapis.com/v1beta/openai/

Untuk akses Gemini melalui router Flatkey yang kompatibel dengan OpenAI, base URL-nya adalah:

https://router.flatkey.ai/v1

Kedua pendekatan ini dapat menjaga aplikasi Anda tetap mirip dengan bentuk OpenAI SDK, tetapi keduanya menyelesaikan masalah yang berbeda. Endpoint langsung Google adalah jalur tercepat ketika Anda hanya membutuhkan Gemini. Jalur router berguna ketika tim Anda menginginkan Gemini, GPT, Claude, DeepSeek, Qwen, dan model lainnya di balik satu gateway, satu alur kunci, satu log penggunaan, dan satu tampilan penagihan.

Panduan ini menjelaskan endpoint resmi Gemini yang kompatibel dengan OpenAI, cara mengonfigurasinya di Python, JavaScript, dan REST, kapan sebaiknya menggunakan Flatkey, dan apa yang perlu diuji sebelum mengirim traffic produksi.

Base URL Resmi Gemini yang Kompatibel dengan OpenAI

Dokumentasi Gemini API dari Google mengonfirmasi bahwa model Gemini dapat diakses melalui library OpenAI Python dan JavaScript, serta REST, dengan mengubah API key, base URL, dan model.

Base URL langsung Gemini yang kompatibel dengan OpenAI adalah:

https://generativelanguage.googleapis.com/v1beta/openai/

Di Python, parameter OpenAI SDK adalah base_url. Di JavaScript, parameternya adalah baseURL. Untuk panggilan REST, endpoint chat completions lengkap menjadi:

https://generativelanguage.googleapis.com/v1beta/openai/chat/completions

Pembedaan ini penting karena banyak masalah konfigurasi berasal dari mencampur base URL SDK dengan endpoint REST lengkap. Jika SDK Anda meminta base_url atau baseURL, gunakan base URL. Jika Anda membuat request HTTP mentah, gunakan path endpoint lengkap.

Endpoint Gemini Langsung vs Router Flatkey

Dua jalur pengaturan ini terlihat mirip dalam kode, tetapi secara operasional berbeda.

Gunakan endpoint Google langsung ketika tujuannya sederhana: memanggil Gemini dengan klien yang kompatibel dengan OpenAI dan mengelola semuanya di dalam lingkungan developer Google.

Gunakan Flatkey ketika panggilan API hanya merupakan bagian dari alur routing yang lebih besar. Jika aplikasi Anda sudah berpindah antar penyedia, melacak penggunaan lintas model, mengelola kuota, atau membutuhkan jalur rollback yang rapi, router dapat mengurangi jumlah logika khusus penyedia di dalam aplikasi.

Setup API Gemini Langsung dengan OpenAI SDK

Jika Anda memanggil Google secara langsung, gunakan Gemini API key Anda dan base URL kompatibel dengan OpenAI milik Google.

Python

from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {
            "role": "user",
            "content": "Balas dengan satu kalimat yang mengonfirmasi bahwa rute Gemini berfungsi."
        }
    ],
)

print(response.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const response = await openai.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    {
      role: "user",
      content: "Balas dengan satu kalimat yang mengonfirmasi bahwa rute Gemini berfungsi.",
    },
  ],
});

console.log(response.choices[0].message.content);

REST

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [
      {
        "role": "user",
        "content": "Balas dengan satu kalimat yang mengonfirmasi bahwa rute Gemini berfungsi."
      }
    ]
  }'

Nama model dapat berubah saat Google memperbarui Gemini. Sebelum digunakan di produksi, pastikan ID model terkini di dokumentasi resmi Gemini API atau lingkungan Google AI Studio Anda.

Gemini Melalui Router Flatkey

Flatkey mempertahankan pola klien yang kompatibel dengan OpenAI, tetapi mengarahkan request Anda ke router Flatkey alih-alih endpoint langsung Google.

Base URL router Flatkey adalah:

https://router.flatkey.ai/v1

Dalam setup ini, Anda menggunakan Flatkey API key dan memilih ID model Gemini dari katalog atau dasbor Flatkey. Jangan berasumsi bahwa setiap string model Google tersedia dengan nama yang sama persis melalui router. Konfirmasikan ID model sebelum melakukan pengujian.

Python

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_GEMINI_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "Balas dengan satu kalimat yang mengonfirmasi bahwa rute Flatkey Gemini berfungsi.",
        }
    ],
)

print(response.choices[0].message.content)
print(response.usage)

JavaScript

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_GEMINI_MODEL,
  messages: [
    {
      role: "user",
      content: "Balas dengan satu kalimat yang mengonfirmasi bahwa rute Flatkey Gemini berfungsi.",
    },
  ],
});

console.log(response.choices[0].message.content);
console.log(response.usage);

Perubahan kode ini kecil, tetapi pengecekan di produksi berbeda. Dengan Flatkey, respons yang berhasil bukan satu-satunya sinyal. Anda juga harus memastikan bahwa permintaan muncul di log penggunaan Flatkey dengan model, status, penggunaan token, dan biaya yang diharapkan.

Base URL Mana yang Harus Anda Gunakan?

Jika tim Anda hanya ingin menguji Gemini dan tidak memerlukan lapisan routing, mulailah dengan endpoint langsung Google:

https://generativelanguage.googleapis.com/v1beta/openai/

Itulah jalur paling bersih untuk integrasi Gemini satu penyedia.

Jika tim Anda sudah mengelola beberapa penyedia model, atau mengharapkan untuk beralih penyedia melalui konfigurasi, gunakan pola router:

https://router.flatkey.ai/v1

Pendekatan router bukan terutama tentang mengubah metode SDK, melainkan menyederhanakan operasional. Alih-alih menaruh kunci khusus penyedia, URL, nama model, log, dan logika rollback di seluruh aplikasi, Anda menyimpan keputusan tersebut lebih dekat ke konfigurasi dan kebijakan routing.

Aturan praktisnya adalah ini: Gemini langsung paling baik untuk integrasi yang terfokus; Flatkey lebih baik ketika Gemini perlu berada di dalam alur kerja akses model yang lebih luas.

Kesalahan Base URL yang Umum

Kesalahan yang paling umum adalah menggunakan kunci yang salah dengan endpoint yang salah. Kunci API Gemini harus digunakan dengan base URL langsung Google. Kunci Flatkey harus digunakan dengan base URL router Flatkey. Jika keduanya tercampur, permintaan bisa gagal bahkan sebelum model dijangkau.

Masalah umum lainnya adalah membingungkan base URL dengan endpoint REST lengkap. Klien SDK biasanya menginginkan base URL:

https://generativelanguage.googleapis.com/v1beta/openai/

Panggilan REST mentah membutuhkan path lengkap:

https://generativelanguage.googleapis.com/v1beta/openai/chat/completions

Tim juga sering mengalami masalah saat mereka hanya menguji completion chat sederhana, tetapi produksi menggunakan streaming, tools, input gambar, embeddings, atau alur kerja file. OpenAI-compatible tidak berarti setiap endpoint dan parameter berperilaku identik di semua penyedia. Perlakukan kompatibilitas sebagai kemudahan bentuk permintaan, bukan janji kesetaraan fitur penuh.

Pengujian Fitur Sebelum Produksi

Migrasi Gemini yang aman dan kompatibel dengan OpenAI harus menguji lebih dari satu respons sukses.

Mulailah dengan completion chat non-streaming dan pastikan aplikasi Anda dapat mem-parsing respons. Lalu periksa nama model, objek usage, bentuk error, dan perilaku timeout. Jika aplikasi produksi Anda menggunakan streaming, function calling, pemahaman gambar, embeddings, atau structured outputs, uji masing-masing jalur tersebut secara terpisah.

Untuk routing Flatkey, tambahkan satu lapisan validasi lagi: pastikan permintaan muncul di dasbor Flatkey. Anda ingin tahu model mana yang digunakan, apakah permintaan berhasil, berapa banyak token yang dihitung, dan biaya apa yang dicatat. Log tersebut adalah salah satu alasan utama menggunakan router sejak awal.

Sebelum mengirim traffic nyata, simpan base URL dan model sebelumnya sebagai nilai rollback. Migrasi yang baik harus bisa dibatalkan hanya dengan mengubah konfigurasi, bukan dengan me-deploy ulang kode aplikasi.

Variabel Lingkungan yang Direkomendasikan

Untuk akses Gemini langsung:

GEMINI_API_KEY="your-gemini-api-key"
OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
GEMINI_MODEL="gemini-3.5-flash"

Untuk routing Flatkey:

FLATKEY_API_KEY="your-flatkey-api-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_GEMINI_MODEL="confirm-this-in-flatkey"

Menyimpan nilai-nilai ini dalam variabel lingkungan memudahkan pengujian dan rollback. Aplikasi dapat terus menggunakan klien yang kompatibel dengan OpenAI sementara konfigurasi menentukan apakah permintaan dikirim langsung ke Google, Flatkey, atau rute kompatibel lainnya.

Kapan Flatkey Memberikan Nilai Tambah

Flatkey tidak diperlukan untuk setiap integrasi Gemini. Jika Anda hanya ingin memanggil Gemini secara langsung dan mengelola kredensial Google sendiri, endpoint resmi sudah cukup.

Flatkey menjadi lebih berguna ketika masalah tim lebih luas daripada satu panggilan model. Misalnya, tim produk mungkin menginginkan Gemini untuk satu alur kerja, GPT untuk alur lain, Claude untuk tugas penulisan yang lebih panjang, dan model lain untuk pekerjaan yang sensitif terhadap biaya. Tanpa router, setiap penyedia dapat membawa pengelolaan kunci, pengecekan harga, log penggunaan, dan pola kegagalannya sendiri.

Router memberi tim satu tempat untuk mengelola akses, memantau penggunaan, membandingkan biaya, dan mengubah rute model. Itu tidak menghilangkan kebutuhan untuk menguji perilaku model, tetapi dapat mencegah peralihan penyedia menyebar ke seluruh codebase.

FAQ

Apa base URL resmi Gemini yang kompatibel dengan OpenAI?

Base URL langsung resminya adalah:

https://generativelanguage.googleapis.com/v1beta/openai/

Gunakan ini dengan kunci API Gemini saat memanggil Google secara langsung melalui SDK yang kompatibel dengan OpenAI.

Haruskah saya menggunakan base_url atau baseURL?

Gunakan base_url di OpenAI SDK untuk Python. Gunakan baseURL di OpenAI SDK untuk JavaScript. Keduanya merujuk pada hal yang sama: base URL yang memberi tahu klien ke mana harus mengirim permintaan.

Apa endpoint REST untuk Gemini chat completions?

Untuk permintaan REST mentah, gunakan:

https://generativelanguage.googleapis.com/v1beta/openai/chat/completions

Jangan gunakan endpoint REST penuh sebagai base URL SDK kecuali klien Anda secara khusus meminta path endpoint penuh.

Base URL apa yang harus saya gunakan untuk Gemini melalui Flatkey?

Gunakan:

https://router.flatkey.ai/v1

Kemudian gunakan kunci API Flatkey dan ID model Gemini yang dikonfirmasi di katalog atau dashboard Flatkey saat ini.

Bisakah saya menggunakan ID model Gemini yang sama di Flatkey?

Tidak secara otomatis. Nama model dan ketersediaannya dapat berbeda menurut penyedia routing dan katalog. Konfirmasikan ID model Flatkey yang tepat sebelum lalu lintas produksi.

Apakah kompatibel dengan OpenAI berarti kesetaraan fitur penuh?

Tidak. Itu berarti endpoint yang didukung dapat menggunakan bentuk request dan response ala OpenAI yang familiar. Anda tetap perlu menguji fitur spesifik yang digunakan aplikasi Anda, terutama streaming, tools, vision, embeddings, dan alur kerja terkait file.

Kesimpulan

Jika Anda mencari endpoint resmi Gemini yang kompatibel dengan OpenAI, gunakan base URL langsung Google:

https://generativelanguage.googleapis.com/v1beta/openai/

Jika Anda ingin Gemini berada dalam alur kerja routing multi-penyedia, gunakan router Flatkey yang kompatibel dengan OpenAI:

https://router.flatkey.ai/v1

Pilihan yang tepat bergantung pada apa yang ingin Anda sederhanakan. Gemini langsung menyederhanakan integrasi satu penyedia. Flatkey menyederhanakan akses model lintas penyedia, visibilitas penggunaan, pengecekan penagihan, dan rollback.

Sebelum produksi, uji model, endpoint, bentuk request, jalur fitur, log penggunaan, dan perilaku kegagalan yang tepat. Penggantian base URL mungkin dapat membuat respons pertama bekerja dengan cepat, tetapi migrasi yang sesungguhnya baru selesai ketika tim mengetahui permintaan itu pergi ke mana, biayanya berapa, dan bagaimana cara kembali jika diperlukan.