API belgeleri

WebSocketOpenAI uyumlu etkinlikler

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.

Model Kimliği
Metin girişiSes çıkışı
WSSwss://api.starsg.ai/v1/realtime?model=tts-altair-v1-mini
Konuş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.

  1. 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 ↗

    bash
    python3 -m venv .venv
    .venv/bin/python -m pip install "openai[realtime]==3.35.1"
  2. 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 ↗

    bash
    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.

  3. Ö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.

    bash
    .venv/bin/python speech.py
    Başarı neye benziyor

    Terminal “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.

python
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.

bash
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.

  1. Almak
    session.created

    Sunucu bir oturum açtı. Artık yapılandırmasını gönderebilirsiniz.

  2. Göndermek
    session.update

    Görevi, ses formatını ve isteğe bağlı sesi ayarlayın.

  3. Almak
    session.updated

    Sunucu yapılandırmayı kabul etti. Şimdi girişi gönderin.

  4. Göndermek
    conversation.item.create

    content.type=input_text ve metninizi içeren content.text ile bir kullanıcı mesajı oluşturun.

  5. Göndermek
    response.create

    Sunucudan metin için ses üretmesini isteyin.

  6. Almak
    response.output_audio.delta

    Base64 delta alanının kodunu çözün ve PCM baytlarını sırayla toplayın. Bu parçalar ayrı WAV dosyaları değildir.

  7. Almak
    response.done

    Response.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
json
{
  "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

modelstringGerekli

WebSocket 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 / ayar tts-altair-v1-mini
AuthorizationstringGerekli

Bağ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 / ayar Bearer <API_KEY>

Oturum ve giriş

session.typestringGerekli

Metinden 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[]Gerekli

Sentez için ses çıkışı isteyin. Bu diziyi session.update'e gönderin.

Örnek / ayar ["audio"]
session.audio.output.formatobjectGerekli

Ses 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ın
Varsayılan / atlanmış Modelin varsayılan sesi
item.content[].textstringGerekli

Sentezlenecek 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 / ayar 1.0
session.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.0
session.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 ↗