Gemini API’yi OpenAI uyumlu istemciyle kullanma: Python ve JavaScript rehberi

Bu rehberde ne öğreneceksiniz?

Bu eğitim, mevcut OpenAI uyumlu istemci kodunu Gemini API’ye yönlendirmek isteyen geliştiriciler için temel bağlantı adımlarını ele alıyor. Google’ın belgelerine göre Gemini modellerine Python ve TypeScript/JavaScript istemci kütüphaneleriyle veya REST API üzerinden erişilebiliyor. Mevcut bir istemci kullananlar için temel geçiş, API anahtarı, istek adresi ve model adını ayarlamak üzerine kurulu.

Örneklerde sohbet tamamlama isteği kullanılıyor. Mimarlık ve iç mekân tasarımı ekipleri, bu temel bağlantı biçimini proje metinleri, tasarım notları veya görsel sunumlarla ilgili sorular için bir uygulamanın parçası olarak değerlendirebilir. Ancak bu rehber yalnızca API bağlantısını gösterir; belirli bir mimari yazılımla entegrasyon, model çıktılarının doğruluğu veya tasarım iş akışına özel bir eklenti sunmaz.

Gereksinimler: anahtar, istemci ve model

Başlamadan önce Google AI Studio’dan alınan bir Gemini API anahtarı gerekir. Google’ın belgesi Python ve JavaScript/TypeScript için OpenAI istemci kütüphanelerini, ayrıca REST isteklerini örnekliyor. Kod örneklerinde kullanılan model adı gemini-3.8-flash; farklı bir uyumlu model tercih edilecekse model alanı buna göre düzenlenmeli. Kaynak, istemci kütüphanesinin sürüm numarası ya da ücret bilgisi vermiyor.

Henüz OpenAI istemci kütüphanelerini kullanmayanlar için Google, Gemini API’yi doğrudan çağırma yolunu öneriyor. Bu nedenle mevcut bir uygulama varsa önce kullanılan istemcinin bu yönteme uygun olup olmadığı, yeni bir uygulama kuruluyorsa doğrudan API seçeneğinin gereksinimlere uyup uymadığı değerlendirilmelidir. Aşağıdaki örneklerde GEMINI_API_KEY yer tutucudur; gerçek anahtar bu metnin yerine kullanılmalıdır.

Adım adım ilk isteği gönderme

1. API anahtarını edinin. Google AI Studio’dan Gemini API anahtarı alın. Anahtar, isteklerin kimlik doğrulamasında kullanılır; örneklerde gerçek bir anahtar değil, yer tutucu bulunur.

2. İstemciyi Gemini uç noktasına yönlendirin. Python örneğinde base_url, JavaScript örneğinde baseURL alanı Gemini API adresini gösterir. Bu ayar, istemcinin isteklerini varsayılan adres yerine belgelenen Gemini adresine gönderir.

3. Model adını belirtin. Örnekte gemini-3.8-flash kullanılıyor. Model adı isteğin içinde ayrı bir alan olarak yer alıyor; başka bir model kullanılacaksa bu alanın seçilen modelle eşleşmesi gerekir.

4. İlk metin isteğini çalıştırın. Aşağıdaki Python örneği, sistem ve kullanıcı mesajlarını sohbet tamamlama isteğinde gönderiyor ve yanıttaki mesajı yazdırıyor. Kod, Google’ın açık lisanslı rehberindeki örnekten alınmıştır.

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.8-flash",
messages=[
{ "role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Explain to me how AI works"
}
]
)
print(response.choices[0].message)

Örnekteki kullanıcı mesajı genel bir açıklama istiyor. Mimarlık odaklı bir uygulamada bu metin, bir proje notunu özetleme isteği gibi uygulamanın amacına uygun içerikle değiştirilebilir. Bu, kodun kullanımına ilişkin bir uyarlamadır; kaynağın belirli bir mimari görev için sonuç garantisi verdiği anlamına gelmez.

1. JavaScript ile aynı temel bağlantıyı kurun. JavaScript örneğinde de API anahtarı, uç nokta, model ve mesajlar tanımlanıyor. İstek tamamlandığında dönen mesaj konsola yazdırılıyor.

import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
const response = await openai.chat.completions.create({
model: "gemini-3.8-flash",
messages: [
{ role: "system",
content: "You are a helpful assistant."
},
{
role: "user",
content: "Explain to me how AI works",
},
],
});
console.log(response.choices[0].message);

1. İstemci kullanmadan REST isteği gönderin. Aşağıdaki cURL örneği, aynı temel işlemi HTTP isteğiyle yapıyor. Anahtar, Authorization başlığında; model ve mesaj ise istek gövdesinde yer alıyor.

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "Explain to me how AI works"
}
]
}'

Üç yöntemde de önemli ortak nokta, isteğin Gemini API’ye yöneltilmesi ve doğru anahtar ile model adının kullanılmasıdır. Google, uyumlu istemcilerle geçişi üç satırdaki ayarı değiştirme yaklaşımıyla özetliyor; bu ifade temel bağlantı ayarlarını anlatır, her uygulamanın başka kod değişikliği gerektirmeyeceği anlamına gelmez.

Sık karşılaşılan hatalar ve kontrol noktaları

• Varsayılan uç noktayı bırakmak: İstemci Gemini API’ye yönlendirilmediyse istek hedefi beklenen adres olmayabilir. Python’da base_url, JavaScript’te baseURL ayarını ve REST adresini kontrol edin.

• Yer tutucuyu değiştirmemek: Örneklerdeki GEMINI_API_KEY gerçek anahtar değildir. Anahtarı Google AI Studio’dan alınan değerle değiştirin.

• Model adını yanlış yazmak: Model alanı örneklerde gemini-3.8-flash olarak gösteriliyor. Seçilen modelin adıyla istekteki değerin aynı olduğunu doğrulayın.

• Uyumluluğu tüm özelliklerde aynı sanmak: Rehber, sohbet tamamlama yanında akış yanıtları, işlev çağırma ve görsel anlama gibi başlıklar da içeriyor. Ancak her birinin isteği ve yapılandırması farklı olabilir; burada verilen temel sohbet örneği bu özelliklerin tüm kurulum ayrıntılarını kapsamaz.

• Düşünme ayarlarını birlikte kullanmak: Belgeler, reasoning_effort ile Gemini’ye özgü thinking_level veya thinking_budget ayarlarının örtüşen işlevleri olduğunu ve aynı anda kullanılmaması gerektiğini belirtiyor. Bu nedenle gelişmiş düşünme ayarlarını eklerken ilgili modelin belgelerini ayrıca inceleyin.

Mimarlık, iç mimarlık ve archviz iş akışlarında bu yaklaşım, mevcut bir istemci üzerinden metin tabanlı API erişimini denemek isteyen geliştiriciler için başlangıç noktası olabilir. Bir ofis içi araca proje açıklamaları veya tasarım notlarıyla ilgili metin istekleri eklemek gibi fikirler test edilebilir; ancak kaynak, belirli yazılımlarla uyumluluk, görsel üretim iş akışı ya da yerel donanım gereksinimi belirtmiyor. Üretim ortamına geçmeden önce lisans ve API maliyetlerini, kullanılan modelin koşullarını ve uygulama içindeki veri akışını ayrıca değerlendirmek gerekir; bu kaynak metin fiyat veya donanım bilgisi sunmuyor.

Sonraki adımlar

İlk metin isteği çalıştıktan sonra Google’ın aynı belgede yer verdiği akış yanıtları, işlev çağırma ve görsel anlama bölümleri incelenebilir. Bunlar temel sohbet örneğine doğrudan eklenmiş hazır özellikler değildir; her biri kendi istek biçimi ve gereksinimleri açısından ele alınmalıdır. Uygulama OpenAI istemci kütüphanesini zaten kullanmıyorsa doğrudan Gemini API seçeneği de başlangıç kararına dâhil edilmelidir.

Mimari ekipler için en güvenli deneme yöntemi, önce hassas olmayan örnek proje metinleriyle küçük bir prototip kurmak ve gelen çıktıları tasarım kararlarının yerine değil, incelenecek yardımcı içerik olarak ele almaktır. Bu öneri, API’nin belirli bir tasarım sonucunu garanti ettiği iddiası değildir; teknik bağlantıyı gerçek iş akışına taşımadan önce ekibin kendi doğrulama sürecini oluşturmasına yönelik pratik bir yaklaşımdır.

Kaynak ve lisans

Bu eğitim, Google’ın Gemini API “OpenAI compatibility” rehberindeki Python, JavaScript ve REST örnekleri temel alınarak Türkçeye uyarlanmıştır. Kaynak CC BY 4.0 lisanslıdır.