Speech to text API, kaydedilmiş sesi yazıya dönüştüren bir hizmettir. Bir toplantıyı aranabilir notlara, bir röportajı düzenlenebilir döküme veya kullanıcıdan gelen sesli mesajı metin alanına çevirmek için kullanılır. Fakat ses dosyasını yükleyip dönen yanıtı ekrana basmak, güvenilir bir ürün akışının yalnızca ilk adımıdır. Kayıt kalitesi, dosya sınırı, izin, gizlilik, hata yönetimi ve insan kontrolü sonucu doğrudan etkiler.
Bu rehberde önce ses dökümünün neyi yapıp neyi yapmadığını açıklayacağız. Ardından tamamlanmış bir dosyayı OpenAI’nin dosya dökümü API’sine gönderen küçük bir örnek, web uygulaması için güvenli mimari, uzun kayıt ve çoklu konuşmacı kararları, doğruluk testleri ve yayın öncesi kontrol listesi gelecek. Örnek bir entegrasyon şablonudur; kendi hesabınızda istek, maliyet ve veri saklama ayarlarını ayrıca doğrulamalısınız.
Speech to text API tam olarak ne yapar?
Konuşma tanıma sistemi ses sinyalindeki örüntülerden sözcükleri tahmin eder ve çoğu zaman noktalama işaretleriyle okunabilir metin üretir. Çıktı, sesin tek doğru ve eksiksiz kaydı değildir. Arka plan gürültüsü, üst üste konuşma, özel ad, aksan veya düşük mikrofon kalitesi bazı sözcükleri değiştirebilir. Model bazen belirsiz bir bölümde kulağa makul gelen fakat söylenmemiş bir ifade de üretebilir. Bu nedenle döküm, özellikle karar doğuran işlerde insanın kontrol edeceği bir taslak olarak düşünülmelidir.
Dosya dökümü ile canlı döküm farklı ihtiyaçlardır. Kaydı bitirdikten sonra dosyayı göndermek, bir röportajı sonradan yazıya aktarmak için uygundur. Konuşma sürerken ekranda altyazı göstermek istiyorsanız gecikme, bağlantı kopması ve parça parça gelen metin için canlı ses mimarisi gerekir. OpenAI’nin güncel dosya dökümü belgesi tamamlanmış kayıt için Transcriptions API’yi, hâlâ gelen ses için Realtime döküm yolunu ayırıyor.
Başlamadan önce kullanım senaryosunu tanımlayın
“Sesi metne çevir” cümlesi ürün gereksinimi olarak yetersizdir. Kullanıcı birkaç saniyelik sesli not mu, iki saatlik toplantı mı, yoksa çok konuşmacılı çağrı mı yükleyecek? Çıktı yalnızca düz metin mi olacak; konuşmacı, zaman damgası veya altyazı dosyası da gerekiyor mu? Dil baştan biliniyor mu? Yanıtın birkaç saniyede gelmesi şart mı? Bu sorular model ve işlem yolunu belirler. Gerekmeyen özellikleri açmak entegrasyonu karmaşıklaştırır.
Örneğin bir içerik editörü 15 dakikalık röportaj kaydını yükleyip metni elle düzeltecekse dosya dökümü yeterlidir. Canlı müşteri temsilcisi ekranı aynı anda konuşma akışı gösterecekse Realtime daha uygun olabilir. Çoklu konuşmacı etiketi önemliyse bunu destekleyen özel yanıt biçimi ve model gerekir. Bir modelin “ses dökümü yapıyor” olması, her biçimde konuşmacı ayrımı veya sözcük düzeyinde zaman damgası verdiği anlamına gelmez.
Güvenli işlem akışı: tarayıcı, sunucu, sağlayıcı
En temel mimaride kullanıcı tarayıcıdan bir dosya seçer; dosya uygulamanızın sunucusuna gider; sunucu dosyayı doğrular ve sağlayıcının API’sine kendi anahtarıyla iletir; dönen metni yalnızca yetkili kullanıcıya gösterir. API anahtarını JavaScript paketine, mobil uygulama içine veya herkese açık bir forma yerleştirmeyin. Görünür istemci kodundaki anahtar kopyalanıp başkaları tarafından kullanılabilir. Sunucunun kimlik doğrulama, hız sınırlama ve boyut kontrolü yapması gerekir.
Ses dosyasına iş kimliği verin; dosya adını güvenilir kimlik olarak kullanmayın. Yükleme tamamlanmadan “döküm hazır” göstermeyin. Büyük bir dosyada istemciye bekliyor, işleniyor, tamamlandı veya hata durumlarını anlaşılır biçimde iletin. İsteği tekrar deneyen kullanıcıya iki ücretli işlem başlatmamak için idempotency veya uygulama düzeyinde iş kontrolü düşünün. Hangi durumların otomatik yeniden deneneceğini, hangilerinin kullanıcı düzeltmesi gerektirdiğini önceden ayırın.
Ses dosyasını hazırlama: biçim ve boyut
Sağlayıcının kabul ettiği dosya türlerini ve üst sınırını yükleme ekranında açıkça gösterin. OpenAI’nin güncel dosya dökümü rehberinde Transcriptions API için 25 MB sınırı; MP3, MP4, MPEG, MPGA, M4A, WAV ve WebM biçimleri listeleniyor. Bu değerleri kalıcı evrensel kural saymayın: servis belgeleri değişebilir ve başka sağlayıcıların sınırları farklı olabilir. Kullanıcıya sunmadan önce seçtiğiniz model ile uç noktanın güncel belgesini kontrol edin.
Dosya uzantısı tek başına güvenlik ve uyumluluk kanıtı değildir. Sunucuda MIME türünü ve gerçek dosya içeriğini doğrulayın, beklenmeyen türleri reddedin ve dosya boyutu sınırını istek işlenmeden uygulayın. Sessiz veya çok kısa kayıtları ayrı ele alın; “başarılı istek” dönse bile kullanışlı bir döküm olmayabilir. WAV büyük dosya oluşturabilir; uzun kayıtları uygun sıkıştırılmış biçimde hazırlamak yükleme süresini azaltabilir, ancak aşırı sıkıştırma anlaşılabilirliği düşürebilir.
25 MB sınırını aşan kayıtta yalnızca dosyayı rastgele parçalara bölmeyin. Konuşmanın ortasından kesilen cümle bağlam kaybı yaratır. Bölümleri sessizlik veya cümle sınırına yakın ayırın; gerekiyorsa kısa örtüşme ve birleştirme kuralı belirleyin. Her parçanın sıra numarasını ve başlangıç zamanını saklayın. Birleştirme sırasında yinelenen sözcükleri ve kaybolan geçişleri insan gözünden geçirin. Daha uzun girdiler için bu yaklaşım OpenAI’nin resmi rehberinde de önerilir.
OpenAI ile en küçük çalışan dosya dökümü örneği
Aşağıdaki örnek sunucu veya geliştirici terminalinde çalıştırılır. Ortam değişkeninde bir API anahtarı bulunduğunu varsayar; anahtarı makaleye, depo dosyasına veya tarayıcıya yazmayın. Önce kısa, paylaşma izni olan bir deneme kaydı seçin. API kullanımının ücret ve erişim koşullarını kendi hesabınızda kontrol edin. Örnek, kaydın konuşulduğu dilde düz metin döndürür; konuşmacı veya sözcük zamanı beklemeyin.
curl --request POST \
--url https://api.openai.com/v1/audio/transcriptions \
--header "Authorization: Bearer $OPENAI_API_KEY" \
--form file=@ornek-kayit.wav \
--form model=gpt-transcribeİstek, dosyayı multipart/form-data gövdesiyle gönderir. Başarılı yanıtın text alanı okunabilir dökümü içerir. OpenAI’nin güncel belge örneği gpt-transcribe modelini başlangıç noktası olarak gösteriyor. Aynı belgedeki model ve parametre desteğini entegrasyonu yayına almadan yeniden okuyun; tarihli makalede verilen adlar ve sınırlar zamanla değişebilir. Hata yanıtında yalnızca HTTP durumunu değil, sağlayıcının açıklamasını da güvenli günlükte inceleyin; bunu kullanıcının ekranına ham olarak dökmeyin.
Uygulamanız Node.js kullanıyorsa dosya yolunu kullanıcıdan doğrudan alıp sunucuda açmayın. Güvenli yükleme alanındaki doğrulanmış dosyayı okuyun. Resmi JavaScript istemcisiyle temel istek openai.audio.transcriptions.create({ file: fs.createReadStream(...), model: "gpt-transcribe" }) biçimindedir. Gerçek uygulamada işin yetkilendirilmesi, geçici dosyanın temizlenmesi, süre aşımı ve hata dönüşü de bu satırın çevresinde olmalıdır. Tek satırlık SDK örneği üretim mimarisi değildir.
Tarayıcıdan mikrofon kaydı alırken
Kullanıcı dosya seçmek yerine tarayıcıda konuşacaksa önce açık bir kayıt düğmesi ve anlaşılır izin açıklaması sunun. navigator.mediaDevices.getUserMedia({ audio: true }) mikrofon izni ister. MDN’ye göre bu çağrı güvenli bağlamda, genellikle HTTPS veya yerel geliştirme ortamında kullanılabilir ve kullanıcı izni gerektirir. İzin verilmezse giriş alanını boş bir “hata” ekranında bırakmayın; dosya yükleme veya elle yazma seçeneği sağlayın.
İzin alınması kaydın başladığı anlamına gelmez. Akışın gerçekten açıldığını, tarayıcının seçtiği biçimi, kaydın bittiğini ve parçaların birleştiğini test edin. Kaydı durdurunca mikrofon akışındaki izleri kapatın. Uzun kaydı bellekte sınırsız tutmak tarayıcıyı yavaşlatabilir. Kayıt süresi ve dosya boyutu için görünür sınır koyun; bağlantı koparsa kullanıcının emeğini kaybetmemesi için ürün gereksinimine uygun geçici saklama davranışı tasarlayın.
Kullanıcıdan aldığınız izni başka bir amaca genişletmeyin. Döküm öncesinde hangi hizmete ses gönderileceğini, sesin ve metnin nerede saklanacağını, ne zaman silineceğini açıkça anlatın. Hassas toplantı, çocuk sesi, sağlık bilgisi veya başka kişilerin konuşması varsa kurum politikasını ve geçerli hukuki yükümlülükleri değerlendirin. Bu rehber hukuki görüş yerine teknik kontrol çerçevesi sunar.
Doğruluk neden değişir ve nasıl ölçülür?
Aynı model iki kayıt üzerinde çok farklı sonuç verebilir. Mikrofona uzaklık, yankı, sokak gürültüsü, telefon hattı, müzik, kesilen cümleler, aksan ve konuşmacıların birbirini bölmesi belirleyicidir. Önce ses kaynağını iyileştirin: mikrofona makul mesafe, sessiz oda, uygun seviye ve tek kanaldaki belirgin konuşma çoğu zaman karmaşık düzeltmelerden daha değerlidir. Kaliteyi yalnızca “daha pahalı model” seçerek çözmeyi beklemeyin.
Test kümesi hazırlarken kolay örnekleri seçmeyin. Kısa sesli not, teknik terim içeren konuşma, iki kişinin sırayla konuştuğu kayıt, üst üste konuşma, gürültü, sessizlik, farklı dil ve zayıf bağlantı koşullarını ayrı değerlendirin. Bir insanın doğru referans dökümüyle karşılaştırma yapın. Sözcük hata oranı gibi sayısal ölçü yararlı olabilir; fakat özel adın yanlış yazılması veya “değil” sözcüğünün atlanması ürün için sıradan bir noktalama hatasından daha ağır olabilir.
Güvenilirlik için inceleme arayüzü sağlayın. Kullanıcı sesin ilgili bölümünü dinleyip metni düzeltebilmeli, düzeltmeyi kaydedebilmeli ve gerekiyorsa dışa aktarabilmelidir. Düzeltilmiş metin ile otomatik ilk taslağı karıştırmayın. Dökümün makine tarafından üretildiğini ve henüz kontrol edilmediğini gösteren bir durum etiketi, özellikle başkalarına iletilecek kayıtlar için faydalıdır. İnsan onayından sonra bile kaynak sesin erişim ve saklama politikasını uygulayın.
Dil, özel ad ve teknik terimler
Birden fazla dil içeren kayıtta otomatik dil algısı her bölümde kusursuz çalışmayabilir. Dil baştan biliniyorsa sağlayıcının desteklediği dil ipucunu kullanmak yararlı olabilir. Ancak parametreler modele göre değişir; seçtiğiniz uç noktanın belge örneğini esas alın. Kullanıcının Türkçe konuştuğu bir kaydı yanlışlıkla İngilizce çeviri isteğine göndermek, hedefiniz özgün dökümse beklenmeyen bir çıktı verir. Ürün ekranında “döküm” ve “çeviri”yi ayrı işlevler olarak adlandırın.
Firma adı, kişi adı, ilaç adı ve kısaltmalarda hata riski yüksektir. OpenAI’nin dosya dökümü rehberi, desteklenen modellerde bağlam veya sözlük niteliğinde ipuçlarının tanımayı iyileştirmeye yardımcı olabileceğini açıklıyor. İpucunu gerçek söylenen sesi zorla başka ifadeye çevirmek için kullanmayın. Özel terimler için kontrollü örnek ses kümesi oluşturup önce ve sonra karşılaştırın. Son metindeki kritik adları insan doğrulamasına bırakın; otomatik düzeltme yeni hatalar da yaratabilir.
Zaman damgası ve konuşmacı ayrımı ne zaman gerekir?
Bir röportajı makale taslağına çevirecekseniz düz metin yeterli olabilir. Video altyazısı için segment zamanları, toplantı tutanağı için konuşmacı etiketleri gerekebilir. Bu çıktılar aynı şey değildir: zaman damgası söylenen bölümün konumunu, konuşmacı etiketi kimin konuştuğuna ilişkin model tahminini verir. Desteklenen model ve response_format birleşimini resmi API şemasından seçin. Her modelin her yanıt biçimini desteklediğini varsaymayın.
Konuşmacı ayrımı kimlik doğrulaması değildir. “Konuşmacı 1” etiketi kişinin adını ispatlamaz; konuşma sırasında ses tonu, örtüşme veya kayıt kalitesi etiketleri karıştırabilir. İsim eşleştirmesini kullanıcı onayıyla yapın. Altyazıda da otomatik zamanların videoyla uyumunu kontrol edin. Tek bir yanlış senkronizasyon uzun video boyunca okunabilirliği bozabilir. Gerekli olmayan ayrıntılı çıktı için daha karmaşık model seçmekten kaçının.
Hata yönetimi ve maliyet kontrolü
Hataları işlem aşamasına göre ayırın. Tarayıcı yüklemeyi bitiremediyse kullanıcıya bağlantı veya dosya boyutu mesajı verin. Sunucu dosyayı reddettiyse izin, biçim veya güvenlik sebebini anlaşılır biçimde söyleyin. Sağlayıcı isteği geçici olarak başarısız olduysa sınırlı yeniden deneme ve artan bekleme kullanın. Kalıcı kimlik doğrulama veya desteklenmeyen biçim hatasını tekrar tekrar göndermek sorunu çözmez. Ham hata gövdesinde kullanıcı verisi bulunabilir; günlüklerin erişimini kısıtlayın.
İstek başına maliyetin yanında depolama, yeniden deneme, uzun iş kuyruğu ve insan düzeltme zamanını da hesaba katın. Kullanıcı bir dosyayı aynı anda iki kez gönderirse yinelenen işi yakalayın. Boş, tamamen sessiz veya bozuk dosyaları API çağrısından önce tespit edin. Üründe dosya uzunluğunu ve beklenen işlem süresini göstermek kullanıcı deneyimini iyileştirir; kesin süre sözü vermeyin. Sağlayıcı fiyatları değiştiğinden yayına çıkmadan önce güncel fiyat sayfasını ayrıca kontrol edin.
Gizlilik, saklama ve erişim kontrolü
Ses çoğu zaman metinden daha fazla kişisel bilgi taşır: ses tonu, arka plandaki kişiler ve ortam ayrıntıları kaydedilir. Hangi seslerin hizmete gönderilebileceğini uygulama politikasıyla belirleyin. İzin ve bilgilendirme metnini gerçek veri akışına göre yazın. Geçici dosya, orijinal ses, ham döküm ve düzeltilmiş metin için ayrı saklama süreleri düşünün. “İş bitti” durumunda gerçekten silinen kopyaların hangileri olduğunu test edin; yalnızca ön yüz listesinden kaldırmak yeterli değildir.
Bir kullanıcının başka kullanıcının iş kimliğini tahmin ederek döküme erişememesi gerekir. Her okuma ve indirme isteğinde yetki kontrolü yapın. Depolama bağlantıları gerekiyorsa kısa ömürlü ve sınırlı yetkili olsun. Loglara tam ses içeriği veya döküm basmayın; hata ayıklama için kimlik, durum ve süre gibi asgari teknik alanları tercih edin. Sağlayıcının veri işleme ve saklama koşullarını ayrıca okuyun. Hassas kullanımda kurumun hukuk ve güvenlik ekipleriyle gerçek veriyi göndermeden karar verin.
Yayın öncesi uygulama kontrol listesi
- Kullanıcıya desteklenen biçimleri, boyut sınırını ve olası beklemeyi açıkça gösterin.
- API anahtarını yalnızca sunucuda tutun; yüklemede kimlik ve yetkiyi doğrulayın.
- Dosya türü, içerik, boyut ve süreyi sunucuda kontrol edin.
- Bekliyor, işleniyor, tamamlandı ve hata durumlarını ayrı gösterin.
- Boş, gürültülü, çok konuşmacılı ve farklı dilli kayıtları test edin.
- Çıktıyı düzenleme ve sesle karşılaştırma olanağı sağlayın.
- Ses, ham döküm ve düzeltilmiş metnin saklama ve silme kurallarını deneyin.
- Tekrar denemelerde yinelenen iş ve beklenmeyen maliyeti önleyin.
Bu listeyi bir kez işaretleyip bırakmayın. Model veya sağlayıcı değişirse aynı test kümesiyle kaliteyi yeniden karşılaştırın. Tarayıcı kayıt akışını da gerçek telefonlarda deneyin. Döküm kalitesini sadece “API 200 döndü” ölçüsüne indirmeyin; kullanıcının metni amacına uygun ve güvenle kullanıp kullanamadığını izleyin.
Sık sorulan sorular
Türkçe konuşma yazıya çevrilebilir mi?
Evet, destekleyen bir model ve anlaşılır kayıtla Türkçe döküm alınabilir. Başarı oranı kayıt ortamına ve kelime dağarcığına bağlıdır. Türkçe özel ad, yer adı ve İngilizce teknik terimlerin karıştığı örnekleri ayrıca test edin. Dil seçimi parametresi varsa model desteğine bakın; tek bir kısa temiz örnekle genel kalite kararı vermeyin.
Canlı altyazı için dosya API’si yeterli mi?
Tamamlanmış dosyayı işleme API’si, her an gelen mikrofon sesi için tasarlanan canlı oturumun yerini doğrudan tutmaz. Dosya işlemede kısmi yanıt akışı olsa bile kayıt önce tamamlanmış olabilir. Canlı altyazıda gecikme, bağlantı ve artımlı düzeltme gereksinimlerini belirleyip Realtime döküm yolunu inceleyin.
API sonucu hukuki veya tıbbi kayıt olarak kullanılabilir mi?
Otomatik dökümü tek başına kesin kayıt kabul etmeyin. Yanlış sözcük veya atlanan olumsuzluk ciddi sonuç doğurabilir. Kaynağı dinleyen yetkili kişinin doğrulaması, kurum prosedürü ve geçerli hukuki gereklilikler gerekir. Bu örnek teknik entegrasyonu anlatır; yüksek riskli kararın doğruluğunu garanti etmez.
Ses dosyasını işlemden sonra silmeli miyim?
Ürünün amacı ve yükümlülükleriyle uyumlu açık bir saklama süresi belirleyin. Kullanıcıya süreyi anlatın ve silme isteğinin geçici dosya ile yedek kopyalara etkisini test edin. Bazı iş akışlarında düzeltme için kayda kısa süreli erişim gerekir; diğerlerinde anında silme daha uygundur. Tek bir evrensel süre yoktur.
Kaynaklar ve ileri okuma
