Konuşmayı metne dönüştürün
WebSocket bağlantısı üzerinden ses gönderin ve transkripsiyon güncellemelerini alın. Bu ilk örnek bir kaydı okur, böylece mikrofonu ayarlamadan akışı öğrenebilirsiniz.
wss://api.starsg.ai/v1/realtime?model=asr-altair-v1-miniKonuşma API'lerinde yeni misiniz? Bu dört terimle başlayın.
- WebSocket
- Programınızın ve sunucunuzun her iki yönde de mesaj alışverişinde bulunabilmesi için açık kalan bir bağlantı.
- Modeli
- Görevi gerçekleştiren motor. Konuşmak için bir tts modeli ve yazıya dökmek için bir asr modeli kullanın; tam genel kimliğini kopyalayın.
- Ses girişi
- Metne dönüştürülecek kayıt. Bu örnekte mono, 24 kHz, 16-bit PCM kullanılır. Python, sesi bir WAV dosyasından okur; Node.js, başlığı olmayan bir PCM dosyasını okur.
- API anahtarı
- Konsolda oluşturulan erişim kimlik bilgileriniz. Bağlantı açıldığında Authorization başlığına gider.
İlk bağlantınız
Entegrasyon yönteminizi ve ortamınızı seçin, ardından aşağıdaki adımları izleyin.
Bir klasör hazırlayın ve kitaplığı yükleyin
Python 3.10 veya üstünü kullanın. Boş bir klasörde bir terminal açın ve resmi OpenAI SDK'yi yükleyin. WebSocket üzerinden konuşma ağ geçidine bağlanır; örnek aşağıdaki versiyonla test edildi. İndirmek ↗
python3 -m venv .venv .venv/bin/python -m pip install "openai[realtime]==3.35.1"
API anahtarınızı ayarlayın
Konsolda bir anahtar oluşturun ve ardından aşağıdaki YOUR_API_KEY anahtarını kendi anahtarınızla değiştirin. Bunu örnekle aynı terminalde çalıştırın. API anahtarlarını yönet ↗
export STARSG_API_KEY="YOUR_API_KEY"
Anahtarınızı gizli tutun. Bunlar yerel/sunucu örnekleridir, tarayıcı kodu değil. Kalıcı bir API anahtarını bir web sayfasına veya genel bir depoya koymayın. Örneği çalıştırmak faturalandırılabilir bir model çağrısı yapar.
Kısa bir kayıt hazırlayın
input.wav'ı aynı klasöre yerleştirin: mono, 24,000 Hz, 16-bit PCM WAV, en az 100 ms konuşma. Ayrıca sentez örneğindeki Output.wav'ı kullanabilir ve onu input.wav olarak yeniden adlandırabilirsiniz.
Kaydınız başka bir format kullanıyorsa FFmpeg'i yükleyin, recording.mp3'yi dosya adınızla değiştirin ve ardından dönüştürün: FFmpeg ↗
ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
Örneği kaydedin ve çalıştırın
Aşağıdaki örneğin tamamını bu klasördeki speech.py adlı yeni bir düz metin dosyasına kopyalayın. Kaydedin ve ardından bu komutu aynı terminalde çalıştırın.
.venv/bin/python speech.py
Başarı neye benziyorTerminal, "Kısmi:" güncellemelerini, ardından "Son:" güncellemelerini ve ardından tamamlanmış transkripsiyonu yazdırabilir. Bazı modeller yalnızca nihai sonucu verebilir.
Tam örnek
Dosyanın tamamını kopyalayın. Bağlanır, oturumu yapılandırır, bir giriş gönderir, tamamlanmasını bekler ve bağlantıyı kapatır. Otomatik olarak yeniden denemez.
import asyncio
import base64
import json
import os
from pathlib import Path
import wave
from openai import AsyncOpenAI
API_KEY = os.environ["STARSG_API_KEY"]
BASE_URL = "https://api.starsg.ai/v1"
MODEL = "asr-altair-v1-mini"
SESSION = json.loads("{\"type\":\"transcription\",\"audio\":{\"input\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000},\"transcription\":{\"model\":\"asr-altair-v1-mini\"},\"turn_detection\":null}}}")
with wave.open("input.wav", "rb") as source:
if (source.getnchannels(), source.getsampwidth(),
source.getframerate(), source.getcomptype()) != (1, 2, 24000, "NONE"):
raise ValueError("Expected mono, 24 kHz, 16-bit PCM WAV")
pcm = source.readframes(source.getnframes())
if len(pcm) < 4800:
raise ValueError("Audio must be at least 100 ms")
async def main():
async with AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL,
max_retries=0) as client:
async with client.realtime.connect(model=MODEL) as connection:
async def receive():
event = (await connection.recv()).model_dump()
if event["type"] == "error" or event["type"].endswith(".failed"):
raise RuntimeError(json.dumps(event.get("error", event), ensure_ascii=False))
return event
async def wait_for(kind):
while True:
event = await receive()
if event["type"] == kind:
return event
await wait_for("session.created")
await connection.session.update(session=SESSION)
await wait_for("session.updated")
for offset in range(0, len(pcm), 4800):
await connection.input_audio_buffer.append(
audio=base64.b64encode(pcm[offset:offset + 4800]).decode()
)
await connection.input_audio_buffer.commit()
transcripts = {}
while True:
event = await receive()
kind = event["type"]
item = (event.get("item_id"), event.get("content_index", 0))
if kind == "conversation.item.input_audio_transcription.delta":
mode = event.get("text_mode", "snapshot")
if mode == "snapshot":
transcripts[item] = event["delta"]
elif mode == "append":
transcripts[item] = transcripts.get(item, "") + event["delta"]
else:
raise ValueError("Unknown text_mode: " + str(mode))
print("Partial:", transcripts[item])
elif kind == "conversation.item.input_audio_transcription.completed":
if not event.get("transcript", "").strip():
raise ValueError("Empty final transcript")
print("Final:", event["transcript"])
return
async def run():
await asyncio.wait_for(main(), timeout=90)
asyncio.run(run())
Örnekte genel bir model kimliği kullanılıyor. Kullanılabilirlik, hesabınıza ve ortamınıza bağlıdır; bu gerçek zamanlı görevi destekleyen bir model seçin. Modelleri görüntüle ↗
Etkinlik akışı
Her mesaj bir JSON olayıdır. Gönder, programınız → sunucunuz anlamına gelir; almak sunucu → programınız anlamına gelir. Girişi göndermeden önce session.updated'ı bekleyin.
- Almak
session.createdSunucu bir oturum açtı. Artık yapılandırmasını gönderebilirsiniz.
- Göndermek
session.updateTranskripsiyon oturumunu, giriş ses formatını, tanıma modelini ve dönüş algılamayı ayarlayın.
- Almak
session.updatedSunucu yapılandırmayı kabul etti. Şimdi girişi gönderin.
- Göndermek
input_audio_buffer.appendBase64 PCM'yi ses alanına gönderin. Bu örnekte, yapılandırılmış biçimde 100 ms'ye eşdeğer olan 4,800 baytlık parçalar kullanılır.
- Göndermek
input_audio_buffer.commitGiriş dönüşünü tamamlayın. turn_detection=null ile açıkça taahhütte bulunmanız gerekir; Tanınması için yanıt.create göndermeyin.
- Almak
conversation.item.input_audio_transcription.deltaDelta ve text_mode'yi okuyun; eşleşen item_id ve content_index'yi güncelleyin.
- Almak
conversation.item.input_audio_transcription.completedTranskript alanı yetkili son metindir. Kaydedin ve ardından bu tek turlu örneği kapatın.
session.update mesajını inceleyin
{
"type": "session.update",
"session": {
"type": "transcription",
"audio": {
"input": {
"format": {
"type": "audio/pcm",
"rate": 24000
},
"transcription": {
"model": "asr-altair-v1-mini"
},
"turn_detection": null
}
}
}
}Parametre referansı
Noktalı adlar, bir alanın JSON nesnesinde nereye ait olduğunu gösterir. Aşağıdaki "gerekli" ifadesi bu kılavuzdaki iş akışı için geçerlidir. Gelişmiş destek ve sınırlar modele bağlıdır.
Bağlantı ve kimlik doğrulama
modelstringGerekliWebSocket URL'de gerekli sorgu parametresi. Gerçek zamanlı katalogdaki tam genel model kimliğini kullanın. ASR ve TTS modelleri birbirinin yerine kullanılamaz.
Örnek / ayarasr-altair-v1-miniAuthorizationstringGerekliBağlantı başlığı: Bearer, bir boşluk, ardından API anahtarınız. Hedef ortamın anahtarını kullanın; URL'ye koymayın.
Örnek / ayarBearer <API_KEY>
Oturum ve giriş
session.typestringGerekliTranskripsiyonu yalnızca tanıma amacıyla kullanın. Asistanın sesli yanıtı oluşturmadan metni döndürür.
Örnek / ayar"transcription"session.audio.input.formatobjectGerekliSes yapılandırması: tür ses/pcm, hız 24000'dir. Bu örnekte mono, imzalı 16 bitli küçük endian örnekleri kullanılır: 48,000 bayt/saniye. WAV başlıkları soket üzerinden gönderilmez.
Örnek / ayar{"type":"audio/pcm","rate":24000}session.audio.input.transcription.modelstringGerekliURL sorgusuyla aynı ASR genel model kimliğini kullanın. Üst satıcının model adını değiştirmeyin.
Örnek / ayarasr-altair-v1-minisession.audio.input.turn_detectionobject | nullİsteğe bağlıÖrnek, otomatik dönüş algılamayı (VAD) devre dışı bırakmak için açıkça null değerini ayarlar. Tüm giriş sesi gönderildiğinde input_audio_buffer.commit'yi gönderin. Bu seçilmiş bir ayardır, sunucu varsayılanıyla ilgili bir iddia değildir.
Örnek / ayarnullaudiostringGerekliinput_audio_buffer.append'deki Base64-encoded ham PCM baytları. Taahhütlü bir sırayla en az 100 ms gönderin. MP3, WAV başlığı, dosya adı veya URL bu alanın yerini alamaz.
Sorun giderme
Önce döndürülen hatayı okuyun. Açık bir bağlantı veya kısmi bir transkript, bu tanınma döngüsünün tamamlandığı anlamına gelmez. Son transkripti bekleyin.
Komut bulunamadı veya eksik modül
Seçilen çalışma zamanını yükleyin, terminalinizi yeniden açın ve proje klasöründeki kurulum komutlarını çalıştırın. Python için yukarıda gösterilen .venv yorumlayıcısını kullanın; benzer adlı websocket paketini değil, websocket-client'ı yükleyin. Node.js örnekleri ws paketini ve bir .mjs dosyasını kullanır.
401 / 403 veya eksik API anahtarı
Ortam değişkeninin bu terminalde ayarlandığını, YOUR_API_KEY'in değiştirildiğini ve anahtarın hedef ortama ait olduğunu kontrol edin. Model erişimini ve hesap durumunu onaylayın. Anahtarı ekran görüntülerinden ve günlüklerden uzak tutun.
El sıkışma başarısız oluyor, 404 / 503 veya model bulunamadı
WSS ana bilgisayar adını, bağlantı noktasını, /v1/realtime yolunu ve tam genel model kimliğini kontrol edin. Hedef ortam için gerçek zamanlı model kataloğunu kullanın. Güvenli olmayan bir HTTP URL'ye yapılan yönlendirmeyi takip etmeyin. 503, servis operatörünün kullanılabilirliği kontrol etmesini gerektirebilir.
Transkript yok veya ses formatı hatası
En az 100 ms konuşma içeren mono, 24 kHz, imzalı 16-bit little-endian PCM kullanın. Python, PCM WAV'ı okur; Node.js, PCM'yi başlık olmadan okur. Yalnızca uzantısını yeniden adlandırmak yerine yukarıdaki komutu kullanarak kaydı dönüştürün.
Zaman aşımı veya bağlantı tamamlanmadan kapanıyor
Örnekler 90 saniye sonra durur. Daha kısa bir giriş deneyin ve ağ erişimini kontrol edin. Kısmi bir transkript veya kısmi ses kaydını başarılı olarak değerlendirmeyin. Yinelenen aramaları önlemek için, yeniden denemeden önce önceki isteğin çalışıp çalışmadığını kontrol edin.
input.wav veya input.pcm bulunamıyor
Kaydı örneğin yanında tutun ve komutu o klasörden çalıştırın. Python input.wav'ı kullanır; Node.js, input.pcm'yi kullanır. Son metin “Final:”dan sonra görünür; tanıma bir ses dosyası oluşturmaz.
Protokol arka planı: OpenAI WebSockets ↗