🎙 Realtime API — Gerçek Zamanlı Sesli Konuşma

WebSocket üzerinden düşük gecikmeli sesli asistan. Ses girer, ses çıkar; arada yazıya çevirmeye gerek yok.

Realtime API, telefon santralinizle veya web uygulamanızla model arasında çift yönlü bir ses kanalı kurar. Kullanıcı konuşurken model dinler, sözü bittiğinde kendiliğinden yanıt üretir ve sesi parça parça geri gönderir. Klasik "kaydet, yazıya çevir, cevap üret, seslendir" zincirinde her adım sıraya girdiği için gecikme birikir; burada tek bağlantı üzerinden aktığı için kullanıcı cevabın başını çok daha erken duyar.

Ne zaman kullanmalı

Bağlantı

GET /v1/realtime?model=openai/gpt-realtime-1.5 HTTP/1.1
Host: api.onysoft.com
Upgrade: websocket
Connection: Upgrade
Authorization: Bearer sk-ony-...

Olay Akışı

Bağlantı kurulduktan sonra her şey JSON olay mesajlarıyla yürür. Tipik bir tur şöyle işler:

1. Bağlanırsınız; sunucu ilk mesaj olarak session.created gönderir.
2. session.update ile ses formatı, ses tonu, konuşma sonu algılama ve transkripsiyon ayarlarını bildirirsiniz.
3. Mikrofondan gelen sesi base64 kodlayıp input_audio_buffer.append ile parça parça akıtırsınız.
4. Sunucu konuşmanın bittiğini algılar (server VAD), input_audio_buffer.speech_stopped gönderir ve yanıt üretmeye başlar.
5. Yanıt sesi response.output_audio.delta olaylarıyla parça parça gelir; siz bunları çalarsınız.
6. response.done olayı turu kapatır ve o turda tüketilen tokenları bildirir — faturalandırma buradan yapılır.

Oturum Ayarları

Bağlandıktan sonra göndereceğiniz ilk mesaj session.update olmalıdır. Aşağıdaki alanlar en çok kullanılanlardır:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "audio": {
      "input": {
        "format":         { "type": "audio/pcmu" },
        "turn_detection": { "type": "server_vad", "create_response": true },
        "transcription":  { "model": "whisper-1", "language": "tr" }
      },
      "output": {
        "format": { "type": "audio/pcmu" },
        "voice":  "marin"
      }
    },
    "instructions": "Türkçe konuş. Kısa ve net yanıt ver.",
    "max_output_tokens": 4096
  }
}

Ses Formatları

Yanlış format en sık karşılaşılan sorundur: ses gider ama karşı taraf gürültü duyar. Hattınıza uygun olanı seçin.

Sık Kullanılan Olaylar

Tam liste uzundur; günlük işte gereken olaylar bunlardır.

Örnek

Bağlanan, ayarları gönderen ve gelen olayları işleyen en küçük çalışan örnek.

import WebSocket from "ws";

const ws = new WebSocket(
  "wss://api.onysoft.com/v1/realtime?model=openai/gpt-realtime-1.5",
  { headers: { Authorization: "Bearer sk-ony-..." } }   // anahtar SUNUCUDA kalir
);

ws.on("open", () => console.log("bagli"));

ws.on("message", (raw) => {
  const e = JSON.parse(raw);
  switch (e.type) {
    case "session.created":
      ws.send(JSON.stringify(sessionUpdate));   // ilk mesaj
      break;
    case "input_audio_buffer.speech_started":
      stopPlayback();                            // soz kesme
      ws.send(JSON.stringify({ type: "response.cancel" }));
      break;
    case "response.output_audio.delta":
      play(Buffer.from(e.delta, "base64"));
      break;
    case "response.done":
      console.log("token:", e.response.usage);  // faturalama bu
      break;
    case "error":
      console.error(e.error.message);
  }
});

// mikrofon sesini base64 kodlayip akit
ws.send(JSON.stringify({ type: "input_audio_buffer.append", audio: chunk.toString("base64") }));

import json, base64, websocket

ws = websocket.create_connection(
    "wss://api.onysoft.com/v1/realtime?model=openai/gpt-realtime-1.5",
    header=["Authorization: Bearer sk-ony-..."],
)

while True:
    e = json.loads(ws.recv())

    if e["type"] == "session.created":
        ws.send(json.dumps(session_update))

    elif e["type"] == "response.output_audio.delta":
        hoparlore_yaz(base64.b64decode(e["delta"]))

    elif e["type"] == "response.done":
        print(e["response"]["usage"])   # token dokumu

    elif e["type"] == "error":
        print("HATA:", e["error"]["message"])

Söz Kesme (Barge-in)

Gerçek bir konuşmada kullanıcı modelin sözünü keser. Bunu doğru yönetmezseniz iki ses üst üste biner. Doğru davranış: input_audio_buffer.speech_started olayını aldığınız anda çalmakta olan sesi durdurun, kuyruğunuzu boşaltın ve response.cancel gönderin. server_vad açıkken sunucu yeni turu kendiliğinden başlatır.

Fonksiyon Çağırma

Asistanın sipariş sorgulaması, randevu açması veya CRM'e yazması gerekiyorsa session.update içinde tools tanımlarsınız. Model gerektiğinde response.function_call_arguments.done olayıyla çağrıyı bildirir; siz işlemi yapıp sonucu conversation.item.create ile geri verirsiniz, ardından response.create ile modelin devam etmesini sağlarsınız.

Süre ve Sınırlar

Faturalandırma

Ücretlendirme gerçek token kullanımına göredir. Oturum kapandığında o oturumda tüketilen giriş ve çıkış tokenları bakiyenizden düşülür; bağlantı süresi için ayrıca bir ücret alınmaz. Ses tokenları metin tokenlarından belirgin biçimde pahalıdır, çünkü bir saniyelik ses birkaç kelimelik metinden çok daha fazla token tutar.

Hata Kodları

Sık Yapılan Hatalar

• Sesi base64 kodlamadan göndermek — sunucu çözemez, ses gitmemiş sayılır.
• Giriş ve çıkış formatını hattınıza uydurmamak; telefonda pcm16 kullanmak cızırtıya yol açar.
• Söz kesmeyi yönetmemek; model konuşurken kullanıcı araya girince iki ses üst üste biner.
• Oturumu 30 dakika sınırına kadar açık tutup yeniden bağlanmayı planlamamak.
• Anahtarı tarayıcıya gömmek. Bağlantıyı daima kendi sunucunuzdan kurun.