API Dokümantasyonu

Mihfar Interface, OpenAI uyumlu bir API geçididir. Mevcut SDK'larınızla çalışır — sadece base URL'i değiştirin. Üstüne Mihfar Akıllı Modeller kazanırsınız.

🚀 Hızlı Başlangıç

1. Hesap oluşturun → Kayıt
2. Dashboard'dan API Anahtarı oluşturun
3. Bakiye yükleyin (Shopier ile TL)
4. Aşağıdaki kodu çalıştırın:

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.mihfar.com/v1",
)

response = client.chat.completions.create(
    model="mihfar-auto",
    messages=[{"role": "user", "content": "Merhaba!"}],
)
print(response.choices[0].message.content)

🔐 Kimlik Doğrulama

Tüm isteklerde Authorization header'ı gereklidir:

Authorization: Bearer sk-your-api-key

API anahtarları Dashboard → API Anahtarları sayfasından oluşturulur.

💳 Bakiye & Fiyatlandırma

• Platform TL (Türk Lirası) üzerinden çalışır.
• Bakiye yüklemek için Dashboard → Bakiye → Shopier ile ödeme yapın.
• Her API isteğinde harcanan TL bakiyenizden otomatik düşülür.
• Bakiyeniz sıfırlandığında istekler 402 hatası verir.

✦ Mihfar Akıllı Modeller

Mihfar, tek bir model ID ile birden fazla modeli yöneten sanal model katmanıdır. Gerçek modeli bilmenize gerek yoktur; Mihfar en uygun modele yönlendirir, biri çalışmazsa zincirdeki sonrakine geçer.

Mihfar Auto Mantığı

Prompt içeriğiniz analiz edilir ve %25 indirimli fiyatla en uygun alt route'a yönlendirilir:

• Görsel içerik → Vision
• Kod anahtar kelimeleri (def, class, bug, import…) → Coder
• Analiz/matematik (adım adım, ispat, hesapla…) → Reason
• Kısa/basit soru → Fast
• Diğer → Smart

🧩 Model Yetenekleri

Her modelin neyi kabul ettiği (girdi modaliteleri), neyi ürettiği (çıktı modaliteleri) ve hangi uçlarda kullanılabildiği (yetenekler) tanımlıdır. İstek sağlayıcıya gitmeden önce bu tanımlara göre doğrulanır — desteklenmeyen bir kullanım 400 ile ve hangi uçları desteklediğini söyleyen bir mesajla reddedilir.

Yetenek	Endpoint	Açıklama
chat	POST /v1/chat/completions	Mesaj tabanlı sohbet
completion	POST /v1/completions	Klasik prompt tamamlama
embedding	POST /v1/embeddings	Metinden vektör
transcription	POST /v1/audio/transcriptions	Konuşmadan metne
translation	POST /v1/audio/translations	Ses → İngilizce metin
speech	POST /v1/audio/speech	Metinden konuşmaya
realtime	WS /v1/realtime	Gerçek zamanlı sesli konuşma
tools	tools alanı	Fonksiyon çağırma
json_mode	response_format	JSON çıktı zorlama
streaming	stream=true	Parça parça yanıt

Modalite kombinasyonları tipik kullanım biçimlerine karşılık gelir:

Girdi → Çıktı	Ne demek
metin → metin	Klasik sohbet / tamamlama
metin, görüntü → metin	Vision — görsel anlama
metin, görüntü, video → metin	Çok modlu analiz
ses → metin	Konuşmadan metne
metin → ses	Metinden konuşmaya
metin, ses → metin, ses	Gerçek zamanlı sesli asistan
metin, dosya → metin	Belge analizi (PDF, doküman)
metin → vektör	Embedding

Ücretlendirme birimi

Metin modelleri token üzerinden ücretlendirilir. Ses modellerinde token sayısı maliyeti temsil etmediği için bu modeller dakika üzerinden faturalanır. Bir modelin hangi birimi kullandığını Fiyatlar sayfasında görebilirsiniz.

Uç	Ücretlendirme
/v1/chat/completions · /v1/completions · /v1/embeddings	Token
/v1/audio/transcriptions · /v1/audio/translations	İşlenen ses süresi (dakika)
/v1/realtime	Oturum süresi (dakika)
/v1/audio/speech	Girdi metni (token)

Dakika bazlı modellerde süre saniye hassasiyetinde ölçülür ve orantılı faturalanır — 30 saniyelik bir ses, dakika fiyatının yarısı kadar tutar. Ücretlendirilen süreyi Kullanım sayfasındaki "Süre" sütununda görebilirsiniz. İndirimler dakika fiyatına da uygulanır.

GET /v1/models

Mihfar sanal modelleri ve sisteme kayıtlı tüm aktif modelleri yetenek dökümüyle döndürür. ?capability= ve ?input_modality= ile filtrelenebilir — örneğin /v1/models?capability=transcription yalnızca ses çeviren modelleri verir.

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "owned_by": "mihfar",
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "capabilities": ["chat", "tools", "streaming"],
      "endpoints": ["POST /v1/chat/completions"],
      "context_length": 128000,
      "max_output_tokens": 16384
    }
  ]
}

GET /v1/models/{id}

Tek bir modelin yetenek dökümü. İstek atmadan önce yetenek kontrolü yapmak için kullanışlıdır.

curl https://api.mihfar.com/v1/models/gpt-4o-realtime-preview \
  -H "Authorization: Bearer sk-key"

POST /v1/chat/completions

Alan	Tür	Açıklama
model	string	Mihfar veya gerçek model ID
messages	array	Rol + içerik mesaj dizisi
stream	boolean	SSE akışı (varsayılan false)
temperature	float	0.0–2.0 yaratıcılık
max_tokens	integer	Maks. yanıt token

curl https://api.mihfar.com/v1/chat/completions \
  -H "Authorization: Bearer sk-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"mihfar-smart","messages":[{"role":"user","content":"Merhaba"}]}'

POST /v1/embeddings

Metni vektör temsillerine dönüştürür. RAG ve semantik arama için.

{ "model": "nomic-embed-text", "input": "Makine öğrenmesi" }

POST /v1/files

Belge yükler ve bir file_id döndürür. Dosya sağlayıcıda saklanır; Mihfar size kendi kimliğini verir, sohbete giderken sağlayıcının kimliğine çevirir. Modelin files yeteneği olmalıdır.

Alan	Tür	Açıklama
file	file	Yüklenecek dosya (zorunlu)
purpose	string	assistants · vision · batch · fine-tune · user_data
model	string	Sağlayıcıyı seçer; verilmezse dosya destekleyen ilk model kullanılır

curl https://api.mihfar.com/v1/files \
  -H "Authorization: Bearer sk-key" \
  -F purpose="assistants" \
  -F file=@"rapor.pdf"

Yanıt:

{
  "id": "file-a1b2c3d4e5f6",
  "object": "file",
  "bytes": 128340,
  "filename": "rapor.pdf",
  "purpose": "assistants",
  "status": "processed"
}

Diğer uçlar:

Uç	Açıklama
GET /v1/files	Dosyalarınızı listeler (?purpose= ile filtrelenir)
GET /v1/files/{id}	Tek dosyanın bilgisi
GET /v1/files/{id}/content	Dosya içeriğini indirir
DELETE /v1/files/{id}	Dosyayı sağlayıcıdan ve kayıttan siler

POST /v1/audio/transcriptions

Konuşmadan metne (speech to text). multipart/form-data ile gönderilir. Model transcription yeteneğine ve audio girdisine sahip olmalıdır.

Alan	Tür	Açıklama
file	file	Ses dosyası (zorunlu)
model	string	Örn. whisper-1
language	string	ISO kodu, örn. tr
response_format	string	json, text, srt, vtt

curl https://api.mihfar.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-key" \
  -F file=@"kayit.mp3" \
  -F model="whisper-1" \
  -F language="tr"

/v1/audio/translations aynı biçimde çalışır, farkı çıktının her zaman İngilizce olmasıdır (translation yeteneği gerekir).

POST /v1/audio/speech

Metinden konuşmaya. Yanıt gövdesi doğrudan ses baytlarıdır — JSON değil.

curl https://api.mihfar.com/v1/audio/speech \
  -H "Authorization: Bearer sk-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","input":"Merhaba dünya","voice":"alloy"}' \
  --output ses.mp3

WS /v1/realtime

Gerçek zamanlı sesli konuşma için çift yönlü WebSocket köprüsü. Mihfar isteği sağlayıcının realtime soketine iletir; sağlayıcı anahtarı istemciye hiç inmez. Oturum boyunca tüketilen token'lar bakiyenizden düşülür.

// Tarayıcıdan doğrudan bağlanma
const ws = new WebSocket(
  "wss://api.mihfar.com/v1/realtime?model=gpt-4o-realtime-preview" +
  "&api_key=sk-key",
  "realtime"
);

ws.onopen = () => ws.send(JSON.stringify({
  type: "session.update",
  session: { modalities: ["text", "audio"], voice: "alloy" }
}));

ws.onmessage = (e) => console.log(JSON.parse(e.data));

Anahtar Authorization: Bearer başlığıyla da verilebilir. Tarayıcı istemcileri için POST /v1/realtime/sessions kısa ömürlü (ephemeral) anahtar üretir; böylece asıl API anahtarınızı istemciye gömmeniz gerekmez.

curl https://api.mihfar.com/v1/realtime/sessions \
  -H "Authorization: Bearer sk-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-realtime-preview","voice":"alloy"}'

🔧 Tool Calling

Modellerin harici fonksiyonları çağırmasını sağlar. Mihfar Smart ve Coder ile en iyi sonuç alınır.

{
  "model": "mihfar-smart",
  "messages": [{ "role": "user", "content": "Hava durumu?" }],
  "tools": [{ "type": "function", "function": {
    "name": "get_weather",
    "parameters": { "type": "object",
      "properties": { "city": { "type": "string" } } }
  }}],
  "tool_choice": "auto"
}

👁️ Vision (Görüntü)

mihfar-vision otomatik vision destekli modele yönlendirir. URL veya Base64 desteklenir.

{
  "model": "mihfar-vision",
  "messages": [{ "role": "user", "content": [
    { "type": "image_url", "image_url": { "url": "https://..." } },
    { "type": "text", "text": "Bu görselde ne var?" }
  ]}]
}

🎬 Video

video girdisini destekleyen modellere mesaj içeriğinde video parçası gönderebilirsiniz. Model bu modaliteyi desteklemiyorsa istek unsupported_modality ile reddedilir.

{
  "model": "gemini-video",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Bu videoda ne oluyor?" },
      { "type": "video_url", "video_url": { "url": "https://..." } }
    ]
  }]
}

Hangi modellerin video kabul ettiğini /v1/models?input_modality=video ile öğrenebilirsiniz.

📎 Dosya Girdisi

file girdisini destekleyen modellere, yüklediğiniz belgeyi mesaj içeriğinde file_id ile gönderebilirsiniz. Model bu modaliteyi desteklemiyorsa istek unsupported_modality ile reddedilir. Destekleyen modelleri /v1/models?input_modality=file ile listeleyebilirsiniz.

{
  "model": "gpt-4o",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Bu raporu özetle" },
      { "type": "file", "file": { "file_id": "file-a1b2c3d4e5f6" } }
    ]
  }]
}

💬 Oturum Yönetimi

Mesaj geçmişini sunucuda saklayan oturum API'si.

⚡ Streaming

"stream": true ile yanıt SSE formatında akar.

curl -N https://api.mihfar.com/v1/chat/completions \
  -H "Authorization: Bearer sk-key" \
  -d '{"model":"mihfar-auto","messages":[...],"stream":true}'

⏱ Rate Limiting

Her kullanıcı için dakika (RPM) ve saat (RPH) limiti uygulanır. Limitler response header'larında bildirilir.

Header	Açıklama
X-RateLimit-Limit-RPM	Dakikada maks. istek
X-RateLimit-Remaining-RPM	Bu dakikada kalan hak
Retry-After	Bekleme süresi (saniye)

⚠️ Hata Kodları

Kod	Açıklama
400	Geçersiz parametre
400 unsupported_capability	Model bu ucu desteklemiyor (yanıt desteklediklerini listeler)
400 unsupported_modality	Model bu girdi türünü kabul etmiyor (görüntü/ses/video)
404 model_not_found	Model bulunamadı veya sisteme eklenmemiş
404 file_not_found	Dosya yok ya da size ait değil
400 file_provider_mismatch	Dosya başka bir sağlayıcıya yüklenmiş
401	Geçersiz veya eksik API anahtarı
402	Yetersiz bakiye
429	Rate limit aşıldı
503	Route zincirindeki modeller kullanılamıyor

❓ SSS

Mihfar modellerini mi yoksa gerçek modelleri mi kullanmalıyım?

Mihfar modellerini öneririz. Fallback zinciri ile yüksek erişilebilirlik sağlarlar ve model değişikliklerinde kod güncellemenize gerek kalmaz.

Fiyatlandırma nasıl çalışır?

Token bazlı, ₺/1M token cinsinden. Güncel liste için Fiyatlar sayfasına bakın. Mihfar Auto %25 indirim uygular.

Hangi gerçek modeller destekleniyor?

Metin, görsel, ses ve gömme (embedding) modelleri. Aktif liste için Modeller sayfasını ziyaret edin.