Metni konuşmaya dönüştürün
WebSocket bağlantısı üzerinden metin gönderin ve sesi parçalar halinde alın. Oynatılabilir bir WAV dosyasını kaydeden eksiksiz bir örnekle başlayın.
wss://api.starsg.ai/v1/realtime?model=tts-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
- Sentez için kullanılan ses. Seçilen modelin kataloğundan bir voice_id seçin; tanımanın sese ihtiyacı yoktur.
- 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.
Ö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 “Kaydedildi:” yazdırır ve çıktı.wav'ı oluşturur. Ses oynatıcınızla açın. Tekrar çalıştırmak için önce o dosyayı yeniden adlandırın veya kaldırın; örnek onun üzerine yazılmayacaktır.
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 = "tts-altair-v1-mini"
SESSION = json.loads("{\"type\":\"realtime\",\"output_modalities\":[\"audio\"],\"audio\":{\"output\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000}}}}")
TEXT = "Merhaba! Bu benim ilk konuşma sentezi örneğim."
OUTPUT = Path("output.wav")
if OUTPUT.exists():
raise FileExistsError("output.wav exists; rename it before running again")
voice = os.environ.get("SPEECH_VOICE")
if voice:
SESSION["audio"]["output"]["voice"] = voice
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")
await connection.conversation.item.create(item={
"type": "message", "role": "user",
"content": [{"type": "input_text", "text": TEXT}]
})
await connection.response.create()
audio = bytearray()
while True:
event = await receive()
if event["type"] == "response.output_audio.delta":
audio.extend(base64.b64decode(event["delta"], validate=True))
elif event["type"] == "response.done":
if event.get("response", {}).get("status") != "completed":
raise RuntimeError("Audio generation did not complete")
if not audio or len(audio) % 2:
raise ValueError("No valid PCM audio received")
with OUTPUT.open("xb") as target:
with wave.open(target, "wb") as wav:
wav.setparams((1, 2, 24000, 0, "NONE", "not compressed"))
wav.writeframes(audio)
print("Saved:", OUTPUT.resolve())
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 ↗
Bir ses seçmek için, o modelin ses kataloğunda voice_id'yi bulun ve çalıştırmadan önce terminalinizde SPEECH_VOICE ayarını yapın. Varsayılan sesi kullanmak için bunu atlayın. "Alaşım" gibi görünen ad voice_id değildir. Aşağıdaki VOICE_ID değerini bu katalogdaki bir değerle değiştirin.
export SPEECH_VOICE="VOICE_ID"
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.updateGörevi, ses formatını ve isteğe bağlı sesi ayarlayın.
- Almak
session.updatedSunucu yapılandırmayı kabul etti. Şimdi girişi gönderin.
- Göndermek
conversation.item.createcontent.type=input_text ve metninizi içeren content.text ile bir kullanıcı mesajı oluşturun.
- Göndermek
response.createSunucudan metin için ses üretmesini isteyin.
- Almak
response.output_audio.deltaBase64 delta alanının kodunu çözün ve PCM baytlarını sırayla toplayın. Bu parçalar ayrı WAV dosyaları değildir.
- Almak
response.doneResponse.status'un tamamlandığını kontrol edin, ardından bir WAV başlığı ekleyin ve toplanan sesi kaydedin. Diğer durumlar başarısızlıktır.
session.update mesajını inceleyin
{
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": [
"audio"
],
"audio": {
"output": {
"format": {
"type": "audio/pcm",
"rate": 24000
}
}
}
}
}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 / ayartts-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.typestringGerekliMetinden konuşmaya oturumu için gerçek zamanı kullanın. Bu bir sentez iş akışıdır, genel bir sesli temsilci görüşmesi değildir.
Örnek / ayar"realtime"session.output_modalitiesstring[]GerekliSentez için ses çıkışı isteyin. Bu diziyi session.update'e gönderin.
Örnek / ayar["audio"]session.audio.output.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.output.voicestringİsteğe bağlıSeçilen modelin ses kataloğundan isteğe bağlı voice_id. Model kapsamına alınmıştır. Sunucu varsayılanı olarak bunu atlayın; satıcının görünen adını kullanmayın. Ses çıkışı başlamadan önce bunu ayarlayın.
Seslere göz atınVarsayılan / atlanmış Modelin varsayılan sesiitem.content[].textstringGerekliSentezlenecek metin, konuşma.item.create → öğe → içerik içinde. İçerik öğesinin türünü input_text, item.type'ı mesaj ve item.role'u kullanıcıya ayarlayın. Metin sınırları modele bağlıdır.
İsteğe bağlı ses kontrolleri
Bu kontroller olmadan başlayın. Eklemeden önce modelin output_controls'sini kontrol edin. Desteklenmeyen ses düzeyi veya perde değerleri hataya neden olur; sessizce göz ardı edilmezler. İlk ses çıkışından sonra ses ve hız kilidi; ses seviyesi ve perde daha sonra güncellenebilir.
session.audio.output.speednumberİsteğe bağlıKonuşma hızı çarpanı: 1.0 normal hızdır. Kabul edilen min/maks değerler modele bağlıdır; kataloğu kontrol edin. İlk çıkış sesinden önce ayarlayın.
Örnek / ayar1.0session.audio.output.options.volumenumber | nullİsteğe bağlıSeçeneklerdeki platform uzantısı: kazanç çarpanı, nötr değer 1.0. Protokol aralığı 0 < hacim ≤ 10'dir, ancak modelin bunu desteklemesi gerekir. Atlanmış veya null nötr değeri kullanır; desteklenmeyen değerler reddedilir.
Varsayılan / atlanmış1.0session.audio.output.options.pitchnumber | nullİsteğe bağlıSeçeneklerde platform uzantısı: yarım tonlarda perde kaydırma, nötr değer 0. Dış protokol aralığı -24 ile 24 arasındadır; bir model daha azına izin verebilir. Reklamı yapılan sınırlarını kullanın. Atlanmış veya boş, nötr perdeyi kullanır.
Varsayılan / atlanmış0
Sorun giderme
Önce döndürülen hata mesajını okuyun. Bağlantının açılması veya bir ses öbeğinin gelmesi, isteğin başarıyla tamamlandığı anlamına gelmez.
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, geçersiz ses veya bozuk oynatma
24 kHz, mono, 16-bit little-endian PCM'yi ve en az 100 ms konuşmayı kontrol edin. Dosyayı yeniden adlandırmak yerine dönüştürme komutunu kullanın. Tanıma, WAV başlığını değil, ham PCM'yi gönderir. Sentez için Base64'nin kodunu çözün ve bir WAV dosyası oluşturmadan önce PCM parçalarını birleştirin.
invalid_value veya desteklenmeyen bir kontrol
İsteğe bağlı hız, ses seviyesi ve perde ayarlarını kaldırın, ardından seçilen model için output_controls'yi kontrol edin. Başka bir modelin voice_id'sini veya sayısal sınırlarını yeniden kullanmayın. Reddedilen bir session.update bu yapılandırmayı uygulamaz.
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.
Output.wav zaten mevcut veya giriş dosyası eksik
Betiği, konuşma.py veya konuşma.mjs'yi içeren klasörden çalıştırın. Buraya input.wav (Python) veya input.pcm (Node.js) koyun. Tekrar oluşturmadan önce önceki çıktı.wav dosyasını yeniden adlandırın. “Son:” satırı tanıma sonucudur; bir ses dosyası oluşturmaz.
Protokol arka planı: OpenAI WebSockets ↗