Çok-Modaliteli Uç Noktalar
Genel Bakış
Apinizer AI Gateway, metin tabanlı sohbet tamamlama uç noktasına ek olarak dört modaliteyi daha destekler — hepsi aynı gateway üzerinden, aynı token kotaları, maliyet takibi ve koruma kontrolleriyle:
- Ses-Metin (STT — Speech to Text) —
/v1/audio/transcriptions - Metin-Ses (TTS — Text to Speech) —
/v1/audio/speech - Görsel Üretim (Image Generation) —
/v1/images/generations - Embedding —
/v1/embeddings
Her uç nokta OpenAI-uyumlu istek/yanıt formatını kullanır; mevcut OpenAI SDK istemcileriniz base_url değişikliği dışında kod değişikliği gerektirmeden çalışır.
Video modalitesi bu kapsamda değildir.
Ses-Metin (STT)
Ses dosyasını metne çevirir:
from openai import OpenAI
client = OpenAI(
api_key="apinizer-kimlik-bilgisi-anahtarınız",
base_url="https://apinizer-gateway-adresiniz.com/api/ai/v1"
)
with open("kayit.mp3", "rb") as audio_file:
transcript = client.audio.transcriptions.create(
model="whisper-1",
file=audio_file
)
print(transcript.text)
- İstek çok parçalı (multipart/form-data) formatında gönderilir
- Kullanım metrikleri ses süresine (duration) dayalı hesaplanır (token sayımı yerine)
- Yanıt metni, mevcut PII maskeleme politikasından geçirilebilir — transkript içinde tespit edilen kişisel veriler diğer metin uç noktalarıyla aynı kurallarla maskelenir
Metin-Ses (TTS)
Metni sese çevirir; yanıt ikili (binary) ses akışı olarak döner:
response = client.audio.speech.create(
model="tts-1",
voice="alloy",
input="Merhaba, bu bir test mesajıdır."
)
response.stream_to_file("cikti.mp3")
TTS yanıtı JSON değil, doğrudan ses dosyası (binary) olarak döner — gateway bu yanıt tipini şeffaf şekilde iletir (pass-through), içerik türü (content-type) korunur.
Görsel Üretim
Metin isteminden görsel üretir:
response = client.images.generate(
model="gpt-image-1",
prompt="Deniz kenarında gün batımı, dijital sanat",
n=1,
size="1024x1024"
)
print(response.data[0].url)
Embedding
Metni sayısal vektöre çevirir — anlamsal arama, RAG ve vektör veritabanı entegrasyonlarında kullanılır:
response = client.embeddings.create(
model="text-embedding-3-small",
input="Apinizer API Management platformu"
)
print(response.data[0].embedding)
Kullanım maliyeti yalnızca girdi (input) token üzerinden hesaplanır — embedding isteklerinde çıkış token'ı yoktur.
Embedding istekleri, yalnızca embedding yeteneğini destekleyen bir sağlayıcı bağlantısına yönlendirilir. Bu yeteneğe sahip olmayan bir bağlantı hedef alınırsa istek reddedilir.
Responses API (/v1/responses)
Sohbet tamamlama uç noktasının yanında, OpenAI'nin /v1/responses uç noktası da desteklenir — OpenAI SDK'sının client.responses.create(...) çağrısıyla kullanılan, konuşma durumunu sağlayıcı tarafında taşıyabilen alternatif istek/yanıt biçimi.
Bu uç nokta yalnızca gerçekten OpenAI Responses API tel-formatını (wire format) konuşan sağlayıcı bağlantılarında çalışır: OpenAI, Azure OpenAI, Özel OpenAI-Uyumlu. Diğer sağlayıcılara (Anthropic, Google Vertex AI, AWS Bedrock, vLLM, Ollama vb.) yönlendirilen bir /v1/responses isteği HTTP 400 ile reddedilir — hiçbir şey denenmez, hiçbir maliyet oluşmaz. Bunun nedeni, previous_response_id/store gibi sağlayıcı tarafı konuşma durumu taşıyan alanları sessizce yok sayacak bir "Responses → Chat" köprüsünün bulunmamasıdır; böyle bir köprü, istemcinin beklediği durum yönetimini fark ettirmeden bozardı.
Akış (streaming) dahil desteklenir; kullanım/maliyet metrikleri diğer uç noktalarla aynı Raporlar ve Analitik altyapısına işlenir — sağlayıcının bu uç noktada farklı bir kullanım alan adlandırması kullanması, maliyet takibinin doğruluğunu etkilemez.
Bilinen v1 Sınırları
- Araç (tool/function) çağrıları otomatik döngüye girmez. Sohbet tamamlama uç noktasındaki çok-turlu araç çağrısı otomasyonu (ajan döngüsü) bu uç nokta için henüz uygulanmadı — model bir araç çağrısıyla yanıt verirse bu, ek bir tur yapılmadan doğrudan istemciye iletilir.
- Yapılandırılmış prompt özellikleri standart
messages[]dizisini okur. Prompt Süsleyici, Prompt Şablonu, Konu-Dışı Koruması, RAG bağlam ekleme ve semantik önbelleğin benzerlik eşleşmesi — hepsi standartmessages[]dizisini okur. Bir Responses isteği bunun yerineinputtaşıdığı için Prompt Süsleyici ve Prompt Şablonu şu an/v1/responsesisteklerinde etkilenmeden geçer (atlanır); Konu-Dışı Koruması, RAG ve semantik önbellek ise isteği mesaj bazında ayrıştırmak yerine isteğin ham metnini tarayarak çalışmaya devam eder. Kişisel veri maskeleme gibi diğer tarama tabanlı korumalar zaten ham istek metni üzerinden (gerekirse kısaltılarak) çalışır ve bu davranıştan etkilenmez. - Metin-dışı modaliteler kapsam dışı. Bu uç nokta yalnızca metin-tabanlı modeller için geçerlidir; embedding veya ses-only bir modele yönlendirilirse istek reddedilir.
Fiyatlandırma ve Kullanım Metrikleri
Her modalite, mevcut AI Maliyet Ayarları ve Raporlar altyapısına entegre edilmiştir:
| Modalite | Fiyatlandırma Birimi | Kullanım Metriği |
|---|---|---|
| STT | Dakika başına | Ses süresi (saniye/dakika) |
| TTS | Karakter başına | Girdi karakter sayısı |
| Görsel Üretim | Görsel başına (boyuta göre) | Üretilen görsel sayısı |
| Embedding | 1M token başına | Girdi token sayısı |
Bu metrikler Raporlar ve Analitik ekranında diğer LLM modelleriyle birlikte, kişi/proje/model kırılımında görüntülenebilir.
Yeni modeller (whisper, tts, gpt-image gibi) Model Kataloğu'nda önceden tanımlı fiyatlarla gelir; ihtiyaç halinde model fiyatlarını AI Maliyet Ayarları sayfasından özelleştirebilirsiniz.
Uç Nokta Yönlendirme
Gateway, gelen isteğin hedef yolunu (/v1/chat/completions, /v1/responses, /v1/audio/transcriptions, /v1/audio/speech, /v1/images/generations, /v1/embeddings) otomatik olarak tanır ve modaliteye özgü işleme hattına (binary yanıt desteği, multipart ayrıştırma, süre bazlı kullanım hesaplama dahil) yönlendirir — ek yapılandırma gerekmez, aynı AI Gateway üzerinden tüm modaliteler sunulabilir.
