OpenRouter: Pratik Örneklerle Bir Rehber

Birden fazla yapay zeka sağlayıcısının API'lerini yönetmek hızla bunaltıcı bir hale gelir. Her sağlayıcının farklı kimlik doğrulama yöntemleri, fiyatlandırma modelleri ve API özellikleri vardır. Geliştiriciler, yalnızca farklı modellere erişmek için OpenAI, Anthropic, Google ve diğer platformlar arasında gidip gelerek sayısız saat harcar.

OpenRouter, düzinelerce sağlayıcıdan 400’den fazla modele bağlayan birleşik bir API sunarak bu karmaşıklığı çözer. GPT-5, Claude 4, Gemini 2.5 Pro ve yüzlerce diğer modele tek bir API anahtarı ve tutarlı bir arayüzle erişebilirsiniz. Platform, perde arkasında otomatik yedekler, maliyet yönetimi ve sağlayıcı yönlendirmesini halleder.

Bu eğitimde, ilk API çağrınızı ayarlamaktan yapılandırılmış çıktılar gibi ileri düzey özellikleri uygulamaya kadar OpenRouter hakkında bilmeniz gereken her şeyi açıklıyorum. Sonunda, tek bir sağlayıcıya bağlı olmayan güvenilir uygulamalar geliştirmeyi öğreneceksiniz.

OpenRouter Nedir?

OpenRouter, tek bir uç noktadan düzinelerce sağlayıcıdan 400’den fazla yapay zeka modeline erişim sağlayan birleşik bir API platformudur. OpenAI, Anthropic, Google, Meta ve diğerleri için ayrı ayrı API anahtarlarıyla uğraşmak yerine, tüm model kataloglarına ulaşmak için tek bir anahtar kullanırsınız.

Platform akıllı bir yönlendirici gibi çalışır, kimlik doğrulama, faturalama ve hata işlemesini üstlenirken isteklerinizi doğru sağlayıcıya gönderir. Bu yaklaşım, birden fazla yapay zeka sağlayıcısı kullanmanın beraberinde getirdiği pek çok sorunu çözer.

OpenRouter’ın çözdüğü sorunlar

Birden fazla yapay zeka sağlayıcıyla çalışmak hızla karmaşıklaşır. Her birinin kendine özgü API biçimi, giriş süreci ve faturalama sistemi vardır. Her hizmet için ayrı kod tabanı tutmak zorunda kalırsınız; bu da geliştirmeyi yavaşlatır ve yeni modelleri denemeyi zahmete dönüştürür.

Sağlayıcılar çöktüğünde veya oran sınırlarına takıldığınızda işler daha da kötüleşir. Uygulamanız bozulur ve beklemekten başka yapacak bir şeyiniz kalmaz. Ayrıca, benzer modeller için hangi sağlayıcının en iyi fiyatı sunduğunu bulmak, farklı platformlardaki maliyetleri elle takip etmeyi gerektirir.

En büyük sorun ise tek bir sağlayıcıya kilitlenmektir. Her şeyi onların özel API’si etrafında inşa ettiğinizde, daha sonra daha iyi modellere veya daha ucuz seçeneklere geçmek büyük bir projeye dönüşür.

OpenRouter bunu nasıl çözer

OpenRouter bu sorunları bir dizi bağlantılı özellikle çözer:

• Tek bir API anahtarı, tüm büyük sağlayıcılardan 400+ modelle çalışır
• İlk tercihiniz başarısız olduğunda otomatik olarak yedek sağlayıcılara geçiş
• Tüm modeller için yan yana fiyatlandırma, böylece maliyetleri anında karşılaştırabilirsiniz
• Mevcut OpenAI koduyla çalışır — yalnızca uç nokta URL’sini değiştirin
• İstekleri en hızlı kullanılabilir sağlayıcıya yönlendiren gerçek zamanlı izleme

Bu parçalar birlikte çalışarak yapay zeka geliştirmesini daha sorunsuz ve güvenilir hale getirir.

Kimler OpenRouter kullanmalı?

Bu birleşik yaklaşımdan farklı kullanıcı türleri fayda sağlar:

• Geliştiriciler, her yerde hesap açmadan yeni modelleri deneyebilir; bu da denemeleri hızlandırır
• Kurumsal ekipler, sağlayıcılar sorun yaşadığında otomatik yedeklerle ihtiyaç duydukları çalışma süresini elde eder
• Bütçe odaklı kullanıcılar, elektronik tablolarla uğraşmadan ihtiyaçları için en ucuz seçeneği bulabilir
• Araştırmacılar, hesap kurulum yükü olmadan en yeni modellere anında erişir

Artık OpenRouter’ın neler sunduğunu anladığınıza göre, ilk API çağrınızı yapacak şekilde sizi ayarlayalım.

Ön Koşullar

OpenRouter’a dalmadan önce, makinenizde birkaç şeyi ayarlamış olmanız gerekir. Bu eğitim, temel Python programlamasında rahat olduğunuzu ve daha önce API’lerle çalıştığınızı varsayar. Uzman olmanıza gerek yok, ancak HTTP istekleri yapma ve JSON yanıtlarını işleme gibi kavramları anlamalısınız.

Sisteminizde Python 3.7 veya üzeri kurulu olmalıdır. OpenRouter'ın API’siyle etkileşim kurmak için openai Python paketini ve ortam değişkenlerini güvenli şekilde yönetmek için python-dotenv paketini kullanacağız. Her ikisini de şu komutla kurabilirsiniz:

pip install requests openai python-dotenv

Ayrıca bir OpenRouter hesabına ve API anahtarına ihtiyacınız olacak. Ücretsiz hesap oluşturmak için openrouter.ai adresine gidin — denemek için küçük bir kredi bakiyesi verilir. Giriş yaptıktan sonra, hesap ayarlarınızda API Keys bölümüne giderek yeni bir anahtar oluşturun.

API anahtarınızı aldıktan sonra, proje dizininizde bir .env dosyası oluşturun ve anahtarınızı şu şekilde ekleyin:

OPENROUTER_API_KEY=your_api_key_here

Bu, API anahtarınızı güvende tutar ve kodunuzun dışında saklar. OpenRouter’ı testin ötesinde kullanmayı planlıyorsanız, Credits sayfası üzerinden hesabınıza kredi eklemeniz gerekir.

Bu temel adımları tamamladıktan sonra, OpenRouter üzerinden ilk API çağrınızı yapmaya hazırsınız.

OpenRouter’da İlk API Çağrınızı Yapma

Daha önce OpenAI SDK kullandıysanız, OpenRouter ile başlamak son derece basittir. Yalnızca bir satır kodu değiştirerek farklı sağlayıcılardan yüzlerce modele anında erişim sağlarsınız.

İlk isteğiniz ve kurulum

OpenRouter’ın yaklaşımını gösteren çalışan bir örnekle doğrudan başlayalım:

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(
   base_url="https://openrouter.ai/api/v1",
   api_key=os.getenv("OPENROUTER_API_KEY"),
)

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "Write a haiku about debugging code at 2 AM"
       }
   ]
)

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

Night hum, coffee cooled
cursor blinks, bug hides somewhere
I chase ghosts 'til dawn

Sihir iki noktada gerçekleşir. Öncelikle, base_url parametresi isteklerinizi OpenAI yerine OpenRouter’ın sunucularına yönlendirir. İkinci olarak, model adı sağlayıcı/model-adı biçimini izler - openai/gpt-5-mini yalnızca gpt-5-mini yerine. Bu, tanıdık arayüzü korurken hangi sağlayıcının sürümünü istediğinizi OpenRouter’a bildirir. Aşağıdaki örneğe hatasız şekilde takabileceğiniz bazı yaygın modeller şunlardır:

• google/gemini-2.0-flash-001
• google/gemini-2.5-pro
• mistralai/mistral-nemo
• deepseek/deepseek-r1-distill-qwen-32b

Farklı modellerle çalışmanın ne kadar kolay olduğunu gördüğünüze göre, seçtiğiniz model kullanılamadığında ne olacağını merak ediyor olabilirsiniz. Sağlayıcılar sorun yaşasa bile güvenilir kalan uygulamaları nasıl inşa edersiniz? İşte OpenRouter’ın yönlendirme ve dayanıklılık özellikleri burada devreye girer.

Dayanıklılık İçin Model Yönlendirme

Güvenilir yapay zeka uygulamaları geliştirmek, beklenmedik durumlara hazırlıklı olmayı gerektirir. Sağlayıcıların kesinti yaşadığı, modellerin oran sınırlarına takıldığı ve bazen içerik denetiminin isteklerinizi engellediği olur. Model yönlendirme, OpenRouter’ın çözümüdür — uygulamanızın sorunsuz çalışmasını sağlamak için farklı modeller arasında otomatik olarak geçiş yapar.

Manuel yedekleri ayarlama

Dayanıklılık eklemenin en basit yolu yedek modeller belirtmektir. Birincil seçeneğiniz başarısız olduğunda, OpenRouter alternatiflerinizi sırayla dener. extra_body parametresi bu yönlendirme talimatlarını OpenRouter'ın API’sine iletir; çünkü OpenAI SDK bu özelliği yerel olarak desteklemez:

response = client.chat.completions.create(
   model="moonshotai/kimi-k2",  # Primary choice
   messages=[
       {"role": "user", "content": "Explain quantum computing in simple terms"}
   ],
   extra_body={
       "models": ["anthropic/claude-sonnet-4", "deepseek/deepseek-r1"]
   }   
)

print(f"Response from: {response.model}")
print(response.choices[0].message.content)

Response from: moonshotai/kimi-k2
Imagine a normal computer bit as a tiny light-switch that can only be OFF (0) or ON (1)...

OpenRouter önce Kimi-K2’yi dener. Kullanılamıyorsa, oran sınırına takılıyorsa veya engellenmişse otomatik olarak Claude Sonnet 4’ü, ardından DeepSeek R1’i dener. response.model alanı, gerçekte hangi modelin yanıt verdiğini gösterir.

Maksimum kolaylık için otomatik yönlendirici

Manuel yedekleri anladıktan sonra, otomatik yönlendirici oldukça cazip hale gelir. Model seçimini ve yedeklemeleri otomatik olarak halleder; bu seçim, NotDiamond’ın değerlendirme sistemi tarafından desteklenir:

response = client.chat.completions.create(
   model="openrouter/auto",
   messages=[
       {"role": "user", "content": "Debug this Python code in 3 sentences: def factorial(n): return n * factorial(n-1)"}
   ]
)

print(f"Auto router selected: {response.model}")
print(response.choices[0].message.content)

Auto router selected: openai/chatgpt-4o-latest
The given code is missing a base case, which causes infinite recursion and eventually a RecursionError. To fix it, add a base case like `if n == 0: return 1` before the recursive call. Here's the corrected version:

\```python
def factorial(n):
   if n == 0:
       return 1
   return n * factorial(n - 1)
\```

Otomatik yönlendirici, isteminizi analiz eder ve kullanılabilir en iyi modeli seçer; ilk tercihiniz kullanılamazsa yerleşik yedekler devreye girer. Böylece herhangi bir yapılandırma olmadan dayanıklılık elde edersiniz. Ancak, otomatik yönlendiriciyi hassas veya yüksek profilli senaryolarda dikkatle kullanın; probleminizin karmaşıklığını olduğundan azımsayıp daha düşük kapasiteli bir modeli seçme eğiliminde olabilir.

Etkili yedekleme stratejileri oluşturma

Tüm modeller birbirleri için iyi bir yedek olmaz. Sağlayıcı kesintileri, o şirkete ait tüm modelleri etkileyebilir; bu nedenle farklı sağlayıcılardan yedekler seçin. Oran sınırları ve maliyetler büyük ölçüde değiştiğinden, pahalı modelleri daha ucuz alternatiflerle eşleştirin:

# Good fallback chain: different providers, decreasing cost
response = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=[
       {"role": "user", "content": "Your prompt here"}
   ],
   extra_body={
       "models": [
           "x-ai/grok-4",                  # Close performance
           "moonshotai/kimi-k2",           # Cheaper
           "deepseek/deepseek-r1:free"     # Free backup
       ]
   }   
)

Bu, mevcut olduğunda üst düzey kalite, yedekte sağlam performans ve son çare olarak garantili erişilebilirlik sağlar. İçerik denetimi politikaları da sağlayıcılar arasında farklılık gösterir; bu nedenle zincirinizi çeşitlendirmek, hassas konular için daha iyi kapsama sunar.

Yedekleme zinciriniz için modeller bulma

The modeller sayfası, zincirinizi oluşturmak için sağlayıcıya ve yeteneklere göre filtreleme yapmanızı sağlar. DeepSeek R1 ve Kimi-K2 gibi birçok güçlü model açık kaynak olduğu için ücretsizdir ve mükemmel yedeklerdir. Ücretsiz modeller, yeni kullanıcılar için günde 50 istek veya 10 kredi satın aldıysanız günde 1000 istek sınırına sahiptir.

Dinamik uygulamalar için, modelleri programlı olarak keşfedebilirsiniz:

def get_provider_models(api_key: str, provider: str) -> list[str]:
   r = requests.get(
       "https://openrouter.ai/api/v1/models",
       headers={"Authorization": f"Bearer {api_key}"}
   )
   return [m["id"] for m in r.json()["data"] if m["id"].startswith(provider)]

# Build fallbacks across providers
openai_models = get_provider_models(api_key, "openai/")
anthropic_models = get_provider_models(api_key, "anthropic/")

Bu yaklaşım, yeni modeller kullanıma sunuldukça uyum sağlayan sağlam yedekleme zincirleri oluşturmanızı sağlar.

Gerçek Zamanlı Yanıtlar İçin Akış

Özellikle daha uzun yanıtlar için yapay zeka modelleriyle çalışırken kullanıcılar, tam yanıtı beklemek yerine çıktının kademeli olarak görünmesini bekler. Akış, yanıt parçalarını oluşturuldukça göndererek bunu çözer; bu da ChatGPT’nin arayüzüne benzer şekilde daha etkileşimli bir deneyim yaratır.

Temel akış kurulumu

OpenRouter’da akışı kurmak için isteğinize stream=True ekleyin. Yanıt, model bunları oluşturdukça parçalar döndüren bir yineleyiciye dönüşür:

response = client.chat.completions.create(
   model="openai/gpt-5",
   messages=[
       {"role": "user", "content": "Write a detailed explanation of how neural networks learn"}
   ],
   stream=True
)

for chunk in response:
   if chunk.choices[0].delta.content is not None:
       print(chunk.choices[0].delta.content, end="")

Her parça, yanıtın küçük bir bölümünü içerir. delta.content alanı yeni metin parçasını tutar ve akış etkisini oluşturmak için bunu satır sonu olmadan anında yazdırırız. end="" parametresi, yazdırma işleminin parçalar arasında yeni satır eklemesini engeller.

Daha iyi bir akış işleyici oluşturma

Üretim uygulamaları için akış süreci üzerinde daha fazla kontrol istersiniz. İşte tamamlanmış yanıtı yöneten daha kapsamlı bir işleyici:

def stream_response(model, messages, show_progress=True):
   response = client.chat.completions.create(
       model=model,
       messages=messages,
       stream=True
   )
  
   complete_response = ""
  
   for chunk in response:
       if chunk.choices[0].delta.content is not None:
           content = chunk.choices[0].delta.content
           complete_response += content
          
           if show_progress:
               print(content, end="", flush=True)
  
   if show_progress:
       print()  # Add final newline
  
   return complete_response

# Use it with different models
result = stream_response(
   "anthropic/claude-sonnet-4",
   [{"role": "user", "content": "Explain quantum entanglement like I'm 12 years old"}]
)

Bu işleyici, ilerlemeyi gösterirken tamamlanmış yanıtı da yakalar; böylece hem akış deneyimini hem de nihai metni elde eder, ayrıca doğru çıktı biçimlendirmesini içerir.

Akış, kullanıcı deneyimini “beklemek ve ummak”tan “ilerlemeyi izlemek”e dönüştürür. Bu, yapay zeka uygulamalarınızı kullanıcılar için çok daha duyarlı ve ilgi çekici hale getirir.

OpenRouter’da Akıl Yürütme Token’larını Yönetme

Bazı yapay zeka modelleri, nihai yanıtı vermeden önce “düşünme” süreçlerini gösterebilir. Bu akıl yürütme token’ları, modelin karmaşık problemlere nasıl yaklaştığına şeffaf bir bakış sunar; sonuçlarına götüren adım adım mantığı gösterir. Bu içsel akıl yürütmeyi anlamak, yanıtları doğrulamanıza, model davranışını ayıklamanıza ve daha güvenilir uygulamalar oluşturmanıza yardımcı olabilir.

Akıl yürütme token’ları nedir

Akıl yürütme token’ları, yanıtta ana içerikten ayrı bir reasoning alanında görünür. Farklı modeller akıl yürütmeyi farklı şekillerde destekler—bazıları efor seviyeleri, bazıları token bütçeleri kullanır. 

İşte akıl yürütmenin iş başında olduğunu gösteren basit bir örnek:

response = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=[
       {"role": "user", "content": "How many 'r's are in the word 'strrawberry'?"}
   ],
   max_tokens=2048,
   extra_body={
       "reasoning": {
           "max_tokens": 512
       }
   }
)

print("Final answer:")
print(response.choices[0].message.content)
print("\nReasoning process:")
print(response.choices[0].message.reasoning)

Final answer:
To count the 'r's in 'strrawberry', I'll go through each letter:
...
There are **4** 'r's in the word 'strrawberry'.

Reasoning process:
...

Model, hem nihai yanıtını hem de o sonuca götüren içsel akıl yürütmeyi gösterir. Bu çiftli çıktı, modelin probleme doğru yaklaşıp yaklaşmadığını anlamanıza yardımcı olur.

Akıl yürütme yoğunluğunu kontrol etme

Modellerin yanıtlarına ne kadar akıl yürütme eforu koyacağını iki yaklaşımla kontrol edebilirsiniz. effort parametresi, OpenAI’nin o-serisi gibi modellerle çalışır ve max_tokens ayarınıza bağlı olarak belirli token yüzdelerine karşılık gelen seviyeler kullanır:

• Yüksek efor: Akıl yürütme için max_tokens değerinin yaklaşık %80’ini kullanır
• Orta efor: Akıl yürütme için yaklaşık %50’sini kullanır
• Düşük efor: Akıl yürütme için yaklaşık %20’sini kullanır

# High effort reasoning for complex problems
response = client.chat.completions.create(
   model="deepseek/deepseek-r1",
   messages=[
       {"role": "user", "content": "Solve this step by step: If a train travels 240 miles in 3 hours, then speeds up by 20 mph for the next 2 hours, how far does it travel total?"}
   ],
   max_tokens=4000,  # High effort will use ~3200 tokens for reasoning
   extra_body={
       "reasoning": {
           "effort": "high" 
       }
   }
)

print("Problem solution:")
print(response.choices[0].message.content)
print("\nStep-by-step reasoning:")
print(response.choices[0].message.reasoning)

Anthropic’in modelleri gibi doğrudan token tahsisini destekleyen modeller için, tam akıl yürütme bütçeleri belirtebilirsiniz:

def get_reasoning_response(question, reasoning_budget=2000):
   response = client.chat.completions.create(
       model="anthropic/claude-sonnet-4",
       messages=[{"role": "user", "content": question}],
       max_tokens=10000,
       extra_body={
           "reasoning": {
               "max_tokens": reasoning_budget  # Exact token allocation
           }
       }
   )
   return response

# Compare different reasoning budgets
response = get_reasoning_response(
   "What's bigger: 9.9 or 9.11? Explain your reasoning carefully.",
   reasoning_budget=3000
)

print("Answer:", response.choices[0].message.content)
print("Detailed reasoning:", response.choices[0].message.reasoning)

Daha yüksek token bütçeleri genellikle daha kapsamlı akıl yürütme üretirken, daha düşük bütçeler daha hızlı ancak daha az ayrıntılı düşünme süreçleri sağlar.

Konuşmalarda akıl yürütmeyi koruma

Çok turlu konuşmalar oluştururken, bağlamı sürdürmek için hem akıl yürütmeyi hem de nihai yanıtı korumanız gerekir. Bu, modelin düşünme sürecinin sonraki yanıtları bilgilendirdiği karmaşık tartışmalar için özellikle önemlidir:

# First message with reasoning
response = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=[
       {"role": "user", "content": "Should I invest in renewable energy stocks? Consider both risks and opportunities."}
   ],
   extra_body={
       "reasoning": {
           "max_tokens": 3000
       }
   }
)

# Build conversation history with reasoning preserved
messages = [
   {"role": "user", "content": "Should I invest in renewable energy stocks? Consider both risks and opportunities."},
   {
       "role": "assistant",
       "content": response.choices[0].message.content,
       "reasoning_details": response.choices[0].message.reasoning_details  # Preserve reasoning
   },
   {"role": "user", "content": "What about solar energy specifically? How does that change your analysis?"}
]

# Continue conversation with reasoning context
follow_up = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=messages,
   extra_body={
       "reasoning": {
           "max_tokens": 2000
       }
   }
)

print("Follow-up answer:")
print(follow_up.choices[0].message.content)
print("\nContinued reasoning:")
print(follow_up.choices[0].message.reasoning)

reasoning_details alanı, tam akıl yürütme zincirini saklayarak, modelin takip sorularını yanıtlarken önceki analizinin üzerine inşa etmesine olanak tanır. Bu, daha tutarlı ve bağlamsal olarak farkında konuşmalar yaratır.

Maliyet ve faturalama hususları

Akıl yürütme token’ları çıktı token’ları olarak faturalandırılır; dolayısıyla kullanım maliyetinizi artırır. Ancak, özellikle hızdan çok doğruluğun önemli olduğu karmaşık görevlerde yanıt kalitesini genellikle yeterince artırarak bu masrafı haklı çıkarırlar. OpenRouter’ın belgelerine göre, akıl yürütme token’ları zorlayıcı problemlerde model performansını artırabilir ve karar sürecine şeffaflık sağlar.

Maliyet odaklı uygulamalar için, görev karmaşıklığına göre efor seviyelerini veya token bütçelerini ayarlayarak akıl yürütme kalitesi ile masraf arasında denge kurabilirsiniz. Basit sorular hiç akıl yürütme gerektirmeyebilirken, karmaşık problemler yüksek eforlu akıl yürütmeden fayda sağlar.

OpenRouter’da Multimodal Modellerle Çalışma

Şimdiye kadar metinle çalıştınız; peki görüntüleri veya belgeleri analiz etmeniz gerektiğinde ne olur? Belki bir grafik hakkında soru sormak, bir PDF’ten bilgi çıkarmak veya bir fotoğrafta neler olup bittiğini tarif etmek istiyorsunuz. İşte multimodal modeller devreye girer — aynı istekte hem metni hem de görsel içeriği anlayabilirler.

Multimodal yetenekleri anlama

Bir resmi metinle tarif etmeye çalışmak yerine, doğrudan görseli gönderebilir ve onunla ilgili sorular sorabilirsiniz. Bu, uygulamalarınızı çok daha sezgisel hale getirir; çünkü model tam olarak neyle çalıştığınızı görür. Metin açıklamanızın tüm önemli ayrıntıları yakalayıp yakalamadığını tahmin etmek zorunda kalmazsınız.

Multimodal modelleri, şimdiye kadar kullandığınız aynı arayüz üzerinden, yalnızca görsel içeriği dahil etmek için ek bir attachments parametresiyle kullanırsınız. Dosya ekleri OpenRouter üzerindeki tüm modellerle çalışır. Bir model yerel olarak PDF’leri veya görüntüleri desteklemese bile, OpenRouter bu dosyaları dahili olarak ayrıştırır ve içeriği modele iletir.

Görüntülerle çalışma

İsteklerinize görüntüleri URL veya base64 kodlama yoluyla dahil edebilirsiniz. Görseliniz zaten çevrimiçiyse, URL yaklaşımı daha basittir:

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "What's happening in this image? Describe the scene in detail."
       }
   ],
   extra_body={
       "attachments": [
           {
               "type": "image/jpeg",
               "url": "https://example.com/photo.jpg"
           }
       ]
   }
)

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

Yerel görseller için base64 kodlama kullanabilirsiniz:

import base64

def encode_image_to_base64(image_path):
   with open(image_path, "rb") as image_file:
       encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
   return encoded_string

# Analyze a local screenshot
encoded_image = encode_image_to_base64("screenshot.png")

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "This is a screenshot of a data dashboard. What insights can you extract from the charts and metrics shown?"
       }
   ],
   extra_body={
       "attachments": [
           {
               "type": "image/png",
               "data": encoded_image
           }
       ]
   }
)

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

Model, genel yanıtlar değil; gördüklerine dayalı somut içgörüler sunmak için gerçek görsele bakar.

PDF belgeleri işleme

PDF işleme aynı şekilde çalışır ancak belge analizinin kapılarını açar. Raporlar hakkında sorular sorabilir, formları analiz edebilir veya karmaşık belgelerden bilgi çekebilirsiniz:

def encode_pdf_to_base64(pdf_path):
   with open(pdf_path, "rb") as pdf_file:
       encoded_string = base64.b64encode(pdf_file.read()).decode('utf-8')
   return encoded_string

# Analyze a research paper
encoded_pdf = encode_pdf_to_base64("research_paper.pdf")

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "Summarize the key findings from this research paper. What are the main conclusions and methodology used?"
       }
   ],
   extra_body={
       "attachments": [
           {
               "type": "application/pdf",
               "data": encoded_pdf
           }
       ]
   }
)

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

Bu, finansal raporlar, akademik makaleler, sözleşmeler veya içeriğin yapay zeka tarafından gerçekten analiz edilmesini istediğiniz herhangi bir PDF için harika çalışır. Karşılaştırma yapmanız veya birden fazla belgeyi birlikte analiz etmeniz gerekiyorsa, tek bir isteğe birden çok ek de dahil edebilirsiniz.

Maliyet ve model seçimi

Multimodal isteklerin maliyeti, yalnızca metin içeren isteklere kıyasla daha yüksektir; çünkü ek veri türleri işlenir. Görseller ve PDF’ler daha fazla hesaplama gücü gerektirir ve bu da fiyatlandırmaya yansır. Her modelin özel multimodal fiyatlandırmasını modeller sayfasında kontrol edebilirsiniz.

Farklı modeller, görsel içerikte farklı güçlü yönlere sahiptir. Bazıları ayrıntılı görüntü analizinde daha iyiyken, diğerleri belge anlamada öne çıkar. Özel ihtiyaçlarınız ve bütçeniz için en iyi sonucu bulmak üzere farklı modelleri denemek isteyeceksiniz.

Yapılandırılmış Çıktıları Kullanma

Gerçek uygulamalar geliştirirken, kodunuzun güvenle ayrıştırabileceği öngörülebilir veri biçimlerine ihtiyacınız vardır. Serbest biçimli metin yanıtları sohbet arayüzleri için harikadır, ancak belirli bilgileri çıkarması gereken uygulamalar için berbattır. Modelin doğru biçimlendirmesini umarak veya regex ile ayrıştırmak yerine, yapılandırılmış çıktılar, modelleri tam olarak ihtiyaç duyduğunuz alanlar ve veri türleriyle garantili JSON döndürmeye zorlar. Bu, ayrıştırma hatalarını ortadan kaldırır ve uygulama kodunuzu çok daha basit hale getirir.

Yapılandırılmış çıktı isteklerinin anatomisi

Yapılandırılmış çıktılar, şu temel yapıya sahip bir response_format parametresi kullanır:

"response_format": {
   "type": "json_schema",           # Always this for structured outputs
   "json_schema": {
       "name": "your_schema_name",  # Name for your schema
       "strict": True,              # Enforce strict compliance
       "schema": {
           # Your actual JSON schema definition goes here
       }
   }
}

Duygu analizi örneği

Metinden duygu çıkaran eksiksiz bir örnekle adım adım ilerleyelim. Bu, yapılandırılmış çıktıların pratikte nasıl çalıştığını gösterir:

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {"role": "user", "content": "Analyze the sentiment: 'This movie was absolutely terrible!'"}
   ],
   extra_body={
       "response_format": {
           "type": "json_schema",
           "json_schema": {
               "name": "sentiment_analysis",
               "strict": True,
               "schema": {
                   "type": "object",
                   "properties": {
                       "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]},
                       "confidence": {"type": "number"}
                   },
                   "required": ["sentiment", "confidence"]
               }
           }
       }
   }
)

import json
result = json.loads(response.choices[0].message.content)
print(result)

{'sentiment': 'negative', 'confidence': 0.98}

Bu şemada neler olduğuna bakalım:

• sentiment: enum kullanılarak üç belirli değerle sınırlandırılmış bir dize alanıdır. Model, "positive", "negative" veya "neutral" dışında bir şey döndüremez
• confidence: Modelin güven puanı için bir sayı alanı
• required: Her iki alan da yanıtta bulunmalıdır - model bunları atlayamaz
• strict: True: Şema yapısına sıkı uyumu zorunlu kılar

Yapılandırılmış çıktılar olmadan, “Duygu çok olumsuz ve güven yüksek” ya da “Negatif (%95 eminim)” gibi yanıtlar alabilirsiniz. Şema ile, kodunuzda anında kullanabileceğiniz ayrıştırılabilir JSON’u her zaman elde edersiniz.

strict: True ayarı şemayı sıkı şekilde uygular—model yapınızdan sapamaz. required dizisi, hangi alanların bulunması gerektiğini belirtir. Değerleri belirli seçeneklerle sınırlamak için enum, listeler için array ve karmaşık veriler için iç içe object türlerini kullanabilirsiniz.

Model uyumluluğu

Tüm modeller yapılandırılmış çıktıları desteklemez, ancak modern olanların çoğu destekler. Uyumluluğu modeller sayfasından kontrol edebilirsiniz. Bir model yapılandırılmış çıktıları yerel olarak desteklemediğinde, OpenRouter çoğu zaman biçimlendirmeyi dahili olarak halleder.

Yapılandırılmış çıktılar, yapay zeka yanıtlarını öngörülemeyen metinden uygulamalarınızın güvenebileceği güvenilir verilere dönüştürür. Tutarlı veri çıkarımı gereken herhangi bir üretim kullanım senaryosu için bu özellik elzemdir.

Sonuç

OpenRouter’ın birleşik API’si aracılığıyla yüzlerce yapay zeka modeline nasıl erişileceğini; ilk isteğinizi yapmaktan akış, akıl yürütme token’ları ve yapılandırılmış çıktılar gibi özellikleri uygulamaya kadar öğrendik.

Platformun otomatik yedekleri ve model yönlendirmesi, bireysel sağlayıcılar sorun yaşadığında bile uygulamalarınızın güvenilir kalmasını sağlar. Aynı kod kalıplarıyla, modelleri karşılaştırabilir, sağlayıcıları değiştirebilir ve birden fazla API anahtarını yönetmeden her görev için mükemmel uyumu bulabiliriz.

Basit isteklerle denemeye başlayın ve ihtiyaçlarınız arttıkça kademeli olarak daha fazla özellik deneyin. Farklı görev türleri için farklı modelleri test edin — bazıları yaratıcı yazımda daha iyi çalışırken, diğerleri veri analizi veya akıl yürütme problemlerinde daha güçlüdür.

Burada edindiğiniz bilgi, tek bir sağlayıcıya kilitli olmayan, yeni model ve yetenekler kullanılabilir hale geldikçe uyum sağlayabilen yapay zeka uygulamaları geliştirmeniz için gerekenleri sunar.