GPT-Realtime-2.1-mini API Nasıl Kullanılır?

Sesli aracıların eskiden üç hareketli parçaya ihtiyacı vardı: konuşmadan metne, bir dil modeli, sonra metinden konuşmaya. Her aşama gecikme ekliyor ve tonu kaybediyordu. OpenAI'ın Gerçek Zamanlı API'si bunu tek bir konuşmadan konuşmaya modeline dönüştürüyor ve gpt-realtime-2.1-mini bu ailenin daha ucuz, daha hızlı katmanıdır. Sesi dinler, düşünür ve tek bir akış bağlantısı üzerinden yanıt verir.

Bu kılavuz size uçtan uca nasıl çağrılacağını gösteriyor: hangi model kimliğini kullanacağınızı, WebSocket ve WebRTC üzerinden nasıl bağlanacağınızı, bir oturumu nasıl şekillendireceğinizi ve bir uygulamaya bağlamadan önce tüm bu sistemi Apidog ile nasıl test edeceğinizi. Buradaki her şey resmi OpenAI Gerçek Zamanlı kılavuzu ile eşleşmektedir.

Öncelikle, model adını doğru alın

Adlandırma insanları şaşırtıyor, bu yüzden herhangi bir kod yazmadan önce bunu açıklığa kavuşturalım. Aynı mini model için iki tanımlayıcı bulunmaktadır:

• gpt-realtime-2.1-mini: sürüm numaralı kimlik. Bu, OpenAI fiyatlandırma sayfasında görünen ve sizi 2.1 nesline sabitleyen kimliktir.
• gpt-realtime-mini: aile takma adı. Her zaman en son anlık görüntüye işaret eder, şu anda gpt-realtime-mini-2025-12-15.

Anlık görüntüler, üretimde davranışı kilitlemenizi sağlar:

Geliştirme yaparken takma adı kullanın, ardından dağıtımdan önce tarihli bir anlık görüntüyü sabitleyin, böylece bir model güncellemesi temsilcinizin davranışını bir gecede asla değiştirmez.

gpt-realtime-2.1-mini ne yapar

Bu, konuşmadan konuşmaya bir modeldir. Sesi akışla gönderirsiniz ve o da doğal tonlamayla, ayrı bir transkripsiyon veya TTS adımı olmadan sesi geri akışla gönderir. Aynı zamanda metni de işler, böylece aynı oturumda yazılı girişi ve konuşulan çıktıyı karıştırabilirsiniz.

İşte model sayfasından teknik özellikler:

marin ve cedar en yeni seslerdir ve sadece Gerçek Zamanlı API'ye özeldir; OpenAI en doğal çıktı için bunları önerir. Belirli bir tını istiyorsanız eski sesler de çalışmaya devam eder.

"Mini" katmanı, daha düşük gecikme ve çok daha düşük maliyet karşılığında biraz akıl yürütme derinliğinden feragat eder. Çoğu destek botu, sipariş alma akışları ve sesli arayüzler için doğru varsayılandır. Tam gpt-realtime-2.1 modeline ancak konuşma daha ağır akıl yürütme gerektirdiğinde başvurun.

Maliyeti nedir

Mini, tam modelin fiyatının yaklaşık üçte biridir. Fiyatlandırma sayfasındaki token oranları:

Ses, faturaya hakimdir ve en büyük maliyet kaldıraçı, temsilcinizin ne kadar konuştuğudur. Dakikada 35 saniye konuşan bir temsilcinin maliyeti, dakikada 15 saniye konuşan bir temsilcinin yaklaşık iki katıdır. Mini için gerçek dünyadaki dakika başına maliyetler, konuşkanlığa bağlı olarak 0,06 ila 0,15 dolar civarında seyreder, bu nedenle modelinize talimatlarda özlü olmasını söyleyerek faturayı doğrudan düşürebilirsiniz. Oranlar değişir, bu nedenle tahminde bulunmadan önce canlı fiyatlandırma sayfasını kontrol edin.

Önkoşullar

Üç şeye ihtiyacınız var:

1. Gerçek Zamanlı erişimli bir OpenAI API anahtarı, OPENAI_API_KEY olarak ayarlanmış.
2. Sunucu örnekleri için Node.js 18+ (ham WebSocket için ws paketi veya resmi openai SDK'sı).
3. Tarayıcı sesi için, getUserMedia'nın çalışabilmesi için HTTPS veya localhost üzerinden sunulan bir sayfa.

Tarayıcıya dokunmadan önce bir kural: gerçek API anahtarınızı asla istemciye göndermeyin. Tarayıcı ve mobil uygulamalar bunun yerine kısa ömürlü geçici tokenlar kullanır. Daha fazlası aşağıda.

Bağlantı yöntemini seçin

Mini model üç taşıma yöntemini destekler. Sesinizin nerede bulunduğuna göre seçim yapın.

Çoğu kişi sunucu tarafı prototip oluşturmak için WebSocket ile başlar, sonra gerçek istemci için WebRTC'ye geçer. İkisini de yapalım.

Hızlı Başlangıç 1: Sunucunuzdan WebSocket

WebSocket, modelin yanıt verdiğini görmenin en hızlı yoludur. Uç nokta, sorgu dizesinde modelin bulunduğu tek bir URL'dir:

wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini

Bu GA arayüzü olduğu için, düz bir Authorization: Bearer başlığı ile kimlik doğrulaması yaparsınız ve artık eski OpenAI-Beta başlığına ihtiyacınız yoktur. İşte bir mikrofon olmadan test edebilmeniz için metin girişi, metin çıkışı "merhaba dünya" örneği:

import WebSocket from "ws";

const url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini";
const ws = new WebSocket(url, {
  headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
});

ws.on("open", () => {
  // 1. Configure the session
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      type: "realtime",
      model: "gpt-realtime-2.1-mini",
      output_modalities: ["text"],
      instructions: "You are a concise API support agent. Keep answers short.",
    },
  }));

  // 2. Add a user message
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [{ type: "input_text", text: "What is an idempotent request?" }],
    },
  }));

  // 3. Ask for a response
  ws.send(JSON.stringify({ type: "response.create" }));
});

ws.on("message", (raw) => {
  const event = JSON.parse(raw.toString());
  if (event.type === "response.output_text.delta") process.stdout.write(event.delta);
  if (event.type === "response.done") ws.close();
});

Akış her zaman aynıdır: yapılandırın, giriş ekleyin, yanıt isteyin, delta'ları dinleyin. Sunucu olayları JSON olarak geri akışla gelir. En çok önem verdikleriniz:

• session.created / session.updated: yapılandırmanız kabul edildi
• response.output_text.delta: bir metin parçası
• response.output_audio.delta: bir base64 ses parçası
• response.output_audio_transcript.delta: modelin söylediklerinin transkripti
• response.done: sıra tamamlandı

Metinden sese geçmek için, output_modalities'i ["audio"] olarak değiştirin ve bir ses yapılandırması ekleyin (bir sonraki bölüm). Ses, response.output_audio.delta olaylarında, çözüp çalabileceğiniz base64 PCM parçaları olarak gelir.

Hızlı Başlangıç 2: Tarayıcıda WebRTC

Gerçek bir sesli uygulama için tarayıcı mikrofonu yakalar ve yanıtı doğrudan oynatır, bu da gecikmeyi düşük tutar. Buradaki sorun kimlik doğrulamasıdır: API anahtarınızı ifşa edemezsiniz, bu yüzden sunucunuz önce kısa ömürlü bir token oluşturur.

Adım 1: Sunucunuzda geçici bir token oluşturun. Gerçek anahtarınızla istemci sırları uç noktasını çağırın:

// server side
const r = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session: { type: "realtime", model: "gpt-realtime-2.1-mini" },
  }),
});
const { value } = await r.json(); // ephemeral key, starts with "ek_"

value değerini tarayıcıya gönderin. Hızlı bir şekilde sona erer, bu nedenle sızıntı riski düşüktür.

Adım 2: Tarayıcıdan WebRTC ile bağlanın. Mikrofonu yakalar, olaylar için bir veri kanalı açar ve /v1/realtime/calls uç noktası ile SDP alışverişi yaparsınız:

// browser side: `EPHEMERAL_KEY` came from your server
const pc = new RTCPeerConnection();

// play the model's audio
pc.ontrack = (e) => (document.getElementById("audio").srcObject = e.streams[0]);

// send the mic
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
pc.addTrack(mic.getTracks()[0]);

// events flow over a data channel
const channel = pc.createDataChannel("oai-events");
channel.onmessage = (e) => console.log(JSON.parse(e.data));

// SDP handshake
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const sdpResp = await fetch(
  "https://api.openai.com/v1/realtime/calls?model=gpt-realtime-2.1-mini",
  {
    method: "POST",
    body: offer.sdp,
    headers: {
      Authorization: `Bearer ${EPHEMERAL_KEY}`,
      "Content-Type": "application/sdp",
    },
  }
);
await pc.setRemoteDescription({ type: "answer", sdp: await sdpResp.text() });

Bağlantı aktif olduğunda, model mikrofon kanalını dinler ve pc.ontrack üzerinden konuşur. Yapılandırmayı ve metni, WebSocket örneğindeki JSON olaylarını kullanarak aynı oai-events veri kanalı üzerinden gönderirsiniz.

Oturumu şekillendirme

session nesnesi, davranışı kontrol ettiğiniz yerdir. Bu, yukarıda gördüğünüzün tam sesli versiyonudur:

{
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2.1-mini",
    output_modalities: ["audio"],
    instructions: "You are a friendly booking assistant. Confirm details before acting.",
    audio: {
      input: {
        format: { type: "audio/pcm", rate: 24000 },
        turn_detection: { type: "semantic_vad" },
      },
      output: {
        format: { type: "audio/pcm", rate: 24000 },
        voice: "marin",
      },
    },
  },
}

Önemli alanlar:

• instructions: sistem isteminiz. Maliyeti önemsiyorsanız kişiliği, koruyucu rayları ve "kısa olun" talimatını ayarlayın.
• output_modalities: konuşan bir aracı için ["audio"], yalnızca transkript sağlayan bir bot için ["text"].
• audio.output.voice: on sesten birini seçin; marin veya cedar en doğal ses verir.
• audio.input.turn_detection: modelin konuşmayı ne zaman bıraktığınıza nasıl karar verdiği. semantic_vad anlamda doğal bir duraklamayı bekler; server_vad sessizlikte tetiklenir. Semantik algılama daha az kesintiye uğratır ve konuşmada daha akıcı hissettirir.

Arama sırasında herhangi bir alanı başka bir session.update göndererek değiştirebilirsiniz. Yeniden bağlanmanız gerekmez.

Aracının eylem yapabilmesi için araçlar ekleme

Sadece sohbet edebilen bir sesli aracı sadece bir demoddur. Bir masa ayırtmak veya bir siparişi kontrol etmek için modelin araçlara ihtiyacı vardır. Gerçek Zamanlı API, platformun geri kalanıyla aynı fonksiyon çağırma sözleşmesini kullanır: fonksiyonları oturumda bildirirsiniz, model bir çağrı yayınlar, siz onu çalıştırırsınız ve sonucu geri beslersiniz. Daha önce chat API'ye araçlar bağladıysanız, bu aynı zihinsel modeldir; OpenAI fonksiyon çağırma hakkındaki kılavuzumuz şemayı derinlemesine ele alır ve yapılandırılmış çıktılar, argümanların katı bir şekle uyması gerektiğinde yardımcı olur.

Araçları oturum içinde tanımlayın, ardından response.function_call_arguments.done olayını işleyin, kodunuzu çalıştırın ve bir sonraki response.create'dan önce sonuçla birlikte bir conversation.item.create gönderin. Birkaç fonksiyondan daha karmaşık herhangi bir şey için, OpenAI'ın AgentKit'i size çok adımlı sesli aracıları düzenlemek için daha üst düzey bir yol sunar.

Uygulamayı geliştirmeden önce uç noktaları Apidog ile test edin

Yarı inşa edilmiş bir uygulamada konsol günlüklerini okuyarak bir REST çağrısını ve bir WebSocket el sıkışmasını ayıklamak istemezsiniz. Önce parçaları ayrı ayrı test edin. İşte Apidog'un gerçek zamanlı bir iş akışında yerini kazandığı yer burasıdır.

İstemci kodu yazmadan önce doğrulamaya değer iki şey:

1. Token uç noktası. POST https://api.openai.com/v1/realtime/client_secrets sıradan bir REST çağrısıdır. Apidog'da bir istek oluşturun, Authorization: Bearer başlığınızı ekleyin, model kimliğinizle JSON gövdesini yerleştirin ve gönderin. ek_ tokenını ve süresinin dolduğunu hemen göreceksiniz, böylece WebRTC devreye girmeden önce anahtarınızın ve hesap erişiminizin iyi olduğunu bileceksiniz. Bu, Yanıtlar API'si gibi OpenAI'ın herhangi bir REST yüzeyini "smoke-test" etmek için kullanacağınız yaklaşımla aynıdır.
2. WebSocket mesaj akışı. Apidog'un bir WebSocket istemcisi vardır, böylece wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini adresine bir bağlantı açabilir, kimlik doğrulama başlığını ekleyebilir ve session.update, conversation.item.create ve response.create mesajlarını teker teker manuel olarak gönderebilirsiniz. Sunucu olaylarının okunabilir bir panelde geri geldiğini izlemek olay dizisini açık hale getirir ve mesajları ekibiniz için örnek olarak kaydedebilirsiniz. Eğer zaten sağlam API test stratejilerine güveniyorsanız, bu tam da yerine oturur.

Taşıma katmanını kendi başına test etmek, uygulamada bir şey bozulduğunda bunun API sözleşmesi olmadığını zaten bildiğiniz anlamına gelir. Takip etmek isterseniz Apidog'u indirin.

Faturayı kontrol altında tutun

Ses çıkışı pahalı kısımdır, bu nedenle birkaç alışkanlık fayda sağlar:

• Modelin özlü olmasını söyleyin. Talimatlarda "Yanıtları bir veya iki cümleyle sınırlayın" demek, ses çıkışı tokenlarını doğrudan azaltır.
• Üretimde bir anlık görüntüyü sabitleyin. gpt-realtime-mini-2025-12-15 değişmeyecektir; gpt-realtime-mini takma adı değişebilir.
• semantic_vad kullanın. Daha az yanlış kesinti, ödediğiniz boşa giden yarı yanıtların azalması anlamına gelir.
• Sistem isteminizi önbelleğe alın. Önbelleğe alınmış giriş, taze metin girişi için 1 milyon başına 0,60 dolara kıyasla 1 milyon başına 0,30 dolardır, bu nedenle sabit bir talimat bloğu her dönüşte daha ucuzdur.
• Boşta kalan oturumları kapatın. Etkin olmayan bir kullanıcıyla açık bir bağlantı, yine de faturalandırılabileceğiniz bir oturumdur.

Yaygın hatalar ve düzeltmeler

• 401 Yetkilendirilmemiş: anahtar yanlış veya süresi dolmuş bir geçici token gönderdiniz. Geçici anahtarlar tasarım gereği kısa ömürlüdür; her oturum için yeni bir tane oluşturun.
• Model bulunamadı: tam kimliği kontrol edin. gpt-realtime-2.1-mini'dir, gpt-realtime-mini-2.1 değil.
• Tarayıcıda ses yok: muhtemelen uzak akışı pc.ontrack'e eklemediniz veya sayfa HTTPS/localhost üzerinde değil, bu yüzden mikrofon hiç açılmadı.
• Model kullanıcının üzerine konuşmayı bırakmıyor: turn_detection'ı semantic_vad'e geçirin ve mikrofon kanalının bağlantıya ulaştığını doğrulayın.
• Beta başlığı gönderme: GA uç noktası OpenAI-Beta: realtime=v1 istemez. Bırakın.

SSS

gpt-realtime-2.1-mini, gpt-realtime-mini ile aynı mı? Etkili bir şekilde evet. gpt-realtime-2.1-mini sürüm numaralı kimliktir, gpt-realtime-mini ise en son anlık görüntüye (gpt-realtime-mini-2025-12-15) işaret eden takma addır. Geliştirme yaparken takma adı kullanın, dağıtım için anlık görüntüyü sabitleyin.

Sesli aracı yerine sadece transkripsiyon için kullanabilir miyim? Gerçek Zamanlı API, etkileşimli konuşmadan konuşmaya için tasarlanmıştır. Tek seferlik transkripsiyon için OpenAI'ın özel transkripsiyon modelleri daha uygun olacaktır. Düşük gecikmeli iki yönlü bir konuşmaya ihtiyacınız olduğunda mini gerçek zamanlı modeli kullanın.

WebRTC'ye ihtiyacım var mı, yoksa WebSocket yeterli mi? WebSocket, sunucu tarafı pipeline'lar ve hızlı prototipler için yeterlidir. Bir tarayıcı veya mobil uygulama sesi doğrudan yakalayıp oynattığında WebRTC kullanın, çünkü medya akışını ve titreşimini sizin için yönetir.

Hangi sesi seçmeliyim? marin ve cedar en yeni ve en doğal seslerdir ve sadece Gerçek Zamanlı API'ye özeldir. Diğer sekiz (alloy, ash, ballad, coral, echo, sage, shimmer, verse) ses, belirli bir ses tonu istiyorsanız hala çalışır.

Bu nasıl faturalandırılır? Modaliteye göre bölünmüş olarak token başına. Mini için: 1 milyon metin girişi başına 0,60 dolar, 1 milyon ses girişi başına 10 dolar ve 1 milyon ses çıkışı başına 20 dolar. Ses çıkışı baskın maliyettir, bu nedenle konuşkanlık ana kaldıraç noktanızdır.

Sohbet modelleri gibi fonksiyonları çağırabilir mi? Evet. Gerçek Zamanlı API aynı fonksiyon çağırma sözleşmesini kullanır, böylece bir sesli aracı siparişleri arayabilir, envanteri kontrol edebilir veya konuşma sırasında eylemleri tetikleyebilir.

Sırada ne var

Artık tüm döngüye sahipsiniz: doğru model kimliği, bir WebSocket prototipi, bir WebRTC tarayıcı istemcisi, oturum yapılandırması, araçlar ve üretimden önce her parçayı Apidog'da test etmenin bir yolu. Erişimi doğrulamak için yalnızca metin içeren WebSocket örneğiyle başlayın, output_modalities'i sese geçirin, ardından gerçek bir mikrofona hazır olduğunuzda WebRTC'ye geçin. Bir anlık görüntüyü sabitleyin, modelin özlü olmasını söyleyin ve faturada sizi şaşırtmayacak düşük gecikmeli bir sesli aracıya sahip olacaksınız.