API belgeleri

WebSocketOpenAI uyumlu etkinlikler

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.

Model Kimliği
Ses girişiMetin çıkışı
WSSwss://api.starsg.ai/v1/realtime?model=asr-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 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.

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

    bash
    ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
  4. Ö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, "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.

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 = "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.

  1. Almak
    session.created

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

  2. Göndermek
    session.update

    Transkripsiyon oturumunu, giriş ses formatını, tanıma modelini ve dönüş algılamayı ayarlayın.

  3. Almak
    session.updated

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

  4. Göndermek
    input_audio_buffer.append

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

  5. Göndermek
    input_audio_buffer.commit

    Giriş 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.

  6. Almak
    conversation.item.input_audio_transcription.delta

    Delta ve text_mode'yi okuyun; eşleşen item_id ve content_index'yi güncelleyin.

  7. Almak
    conversation.item.input_audio_transcription.completed

    Transkript alanı yetkili son metindir. Kaydedin ve ardından bu tek turlu örneği kapatın.

session.update mesajını inceleyin
json
{
  "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

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 asr-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

Transkripsiyonu 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.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.input.transcription.modelstringGerekli

URL sorgusuyla aynı ASR genel model kimliğini kullanın. Üst satıcının model adını değiştirmeyin.

Örnek / ayar asr-altair-v1-mini
session.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 / ayar null
audiostringGerekli

input_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 ↗