DEV Community

Cover image for GPT-Realtime-2.1-mini API Nasıl Kullanılır?
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

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

Sesli aracı mimarisi eskiden üç ayrı adımdan oluşurdu: konuşmadan metne, dil modeli, ardından metinden konuşmaya. Her adım gecikme ekler ve ton bilgisini kaybettirebilir. OpenAI Gerçek Zamanlı API, bunu tek bir konuşmadan konuşmaya modele indirir. gpt-realtime-2.1-mini, bu ailenin daha düşük maliyetli ve daha hızlı katmanıdır: sesi dinler, yanıtı üretir ve aynı akış bağlantısı üzerinden geri konuşur.

Apidog'u bugün deneyin

Bu rehberde gpt-realtime-2.1-mini ile uçtan uca nasıl çalışacağınızı göreceksiniz: doğru model kimliğini seçme, WebSocket ve WebRTC ile bağlanma, oturumu yapılandırma, araç çağırma ekleme ve uygulamaya bağlamadan önce akışı Apidog ile test etme. Akış, resmi OpenAI Gerçek Zamanlı kılavuzu ile uyumludur.

Önce model adını doğru seçin

Aynı mini model için iki pratik kimlik vardır:

  • gpt-realtime-2.1-mini: sürüm numaralı kimliktir. 2.1 nesline sabitler ve OpenAI fiyatlandırma sayfasında bu şekilde görünür.
  • gpt-realtime-mini: aile takma adıdır. En son mini anlık görüntüye işaret eder; şu anda gpt-realtime-mini-2025-12-15.

Üretimde davranışı sabitlemek için tarihli anlık görüntü kullanın:

Tanımlayıcı Neyi işaret ediyor
gpt-realtime-mini En son mini anlık görüntü; otomatik güncellenir
gpt-realtime-2.1-mini 2.1 nesli mini
gpt-realtime-mini-2025-12-15 Sabitlenmiş mevcut anlık görüntü
gpt-realtime-mini-2025-10-06 Sabitlenmiş önceki anlık görüntü

Geliştirmede takma adı kullanabilirsiniz. Dağıtımdan önce tarihli bir anlık görüntüye geçmek, model güncellemesinin temsilci davranışını beklenmedik şekilde değiştirmesini engeller.

gpt-realtime-2.1-mini

gpt-realtime-2.1-mini ne yapar?

gpt-realtime-2.1-mini, konuşmadan konuşmaya çalışan bir modeldir. Sesi akış olarak gönderirsiniz; model ayrı bir transkripsiyon veya TTS adımı olmadan doğal tonlamayla ses yanıtı döndürür. Aynı oturumda metin girişi ve ses çıkışını da birlikte kullanabilirsiniz.

Model sayfasındaki temel özellikler:

Özellik Değer
Giriş modaliteleri Metin, görsel, ses
Çıkış modaliteleri Metin, ses
Bağlam penceresi 32.000 token
Maksimum çıkış 4.096 token
Bağlantılar WebRTC, WebSocket, SIP
Sesler alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar

marin ve cedar, Gerçek Zamanlı API'ye özel en yeni seslerdir. OpenAI, en doğal çıktı için bu sesleri önerir. Belirli bir karakter veya tını istiyorsanız eski sesler de kullanılabilir.

Mini katman, daha düşük gecikme ve maliyet için tam modele göre daha az akıl yürütme derinliği sunar. Destek botları, sipariş alma akışları ve sesli arayüzler için genellikle doğru başlangıç noktasıdır. Daha ağır akıl yürütme gerekiyorsa tam gpt-realtime-2.1 modelini değerlendirin.

Maliyet

Mini, tam modelden belirgin şekilde daha ucuzdur. Fiyatlandırma sayfasındaki oranlar:

Model Metin girişi Önbelleğe alınmış giriş Ses girişi Ses çıkışı
gpt-realtime-2.1-mini $0.60 / 1M $0.30 / 1M $10 / 1M $20 / 1M
gpt-realtime-2.1 $4.00 / 1M $0.40 / 1M $32 / 1M $64 / 1M

Ses çıkışı faturadaki en büyük kalemdir. Temsilciniz ne kadar çok konuşursa maliyet o kadar artar. Örneğin dakikada 35 saniye konuşan bir temsilci, dakikada 15 saniye konuşana göre yaklaşık iki kat maliyet üretebilir.

Pratik kural: sistem talimatında kısa yanıt vermesini söyleyin.

Yanıtları mümkün olduğunda 1-2 cümleyle sınırla.
Gereksiz açıklama yapma.
Kullanıcı isterse ayrıntıya gir.
Enter fullscreen mode Exit fullscreen mode

Oranlar değişebilir; tahmin yapmadan önce güncel fiyatlandırmayı kontrol edin.

Önkoşullar

Başlamadan önce şunlara ihtiyacınız var:

  1. Gerçek Zamanlı API erişimi olan bir OpenAI API anahtarı.
  2. Sunucu örnekleri için Node.js 18+.
  3. WebSocket örneği için ws paketi.
  4. Tarayıcı sesi için HTTPS veya localhost.
  5. Ortam değişkeni: 
export OPENAI_API_KEY="sk-..."
Enter fullscreen mode Exit fullscreen mode

Tarayıcı veya mobil istemciye gerçek API anahtarınızı göndermeyin. İstemciler kısa ömürlü geçici token kullanmalıdır.

Bağlantı yöntemini seçin

gpt-realtime-2.1-mini üç taşıma yöntemini destekler:

Taşıma yöntemi Ne zaman kullanılır? Kimlik doğrulama
WebRTC Ses tarayıcıda veya mobil uygulamada yakalanıp oynatılıyorsa Geçici istemci sırrı
WebSocket Sunucunuz ham sesi veya mesaj akışını yönetiyorsa Sunucu tarafı API anahtarı
SIP Telefon veya telefon sistemi bağlıyorsanız API anahtarı

Genel yaklaşım:

  1. Sunucuda WebSocket ile hızlı prototip oluşturun.
  2. Model erişimini ve mesaj akışını doğrulayın.
  3. Gerçek tarayıcı/mobil ses için WebRTC'ye geçin.

Hızlı başlangıç 1: Sunucudan WebSocket

WebSocket uç noktası:

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

GA arayüzünde Authorization: Bearer başlığı yeterlidir. Eski OpenAI-Beta başlığını göndermeniz gerekmez.

Aşağıdaki örnek mikrofon kullanmadan metin gönderir ve metin yanıtı alır.

Kurulum 

npm install ws
Enter fullscreen mode Exit fullscreen mode

WebSocket ö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. Oturumu yapılandır
  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. Kullanıcı mesajı ekle
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [
        {
          type: "input_text",
          text: "What is an idempotent request?",
        },
      ],
    },
  }));

  // 3. Yanıt oluştur
  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();
  }
});

ws.on("error", console.error);
Enter fullscreen mode Exit fullscreen mode

Temel akış her zaman aynıdır:

  1. session.update ile oturumu yapılandırın.
  2. conversation.item.create ile giriş ekleyin.
  3. response.create ile yanıt isteyin.
  4. Delta olaylarını dinleyin.

Sık kullanılan olaylar:

Olay Anlamı
session.created Oturum oluşturuldu
session.updated Yapılandırma kabul edildi
response.output_text.delta Metin yanıt parçası
response.output_audio.delta Base64 ses parçası
response.output_audio_transcript.delta Modelin konuştuğu sesin transkripti
response.done Yanıt tamamlandı

Metinden sese geçmek için output_modalities değerini ["audio"] yapın ve ses yapılandırması ekleyin.

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

Gerçek sesli uygulamada tarayıcı mikrofonu yakalar ve modelin sesini doğrudan oynatır. Bunun için gerçek API anahtarı yerine kısa ömürlü token gerekir.

Adım 1: Sunucuda geçici token oluşturun 

// 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(); // "ek_" ile başlayan geçici anahtar

// Bu value değerini tarayıcıya gönderin.
Enter fullscreen mode Exit fullscreen mode

value kısa sürede sona erer. Her istemci oturumu için yeni token üretin.

Adım 2: Tarayıcıdan WebRTC ile bağlanın

HTML tarafında model sesini çalmak için bir <audio> elementi ekleyin:

<audio id="audio" autoplay></audio>
Enter fullscreen mode Exit fullscreen mode

Tarayıcı kodu:

// browser side: EPHEMERAL_KEY sunucunuzdan geldi
const pc = new RTCPeerConnection();

// Modelin sesini oynat
pc.ontrack = (event) => {
  document.getElementById("audio").srcObject = event.streams[0];
};

// Mikrofonu yakala ve bağlantıya ekle
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
pc.addTrack(mic.getTracks()[0]);

// Olaylar veri kanalı üzerinden akar
const channel = pc.createDataChannel("oai-events");

channel.onopen = () => {
  console.log("Realtime data channel opened");

  channel.send(JSON.stringify({
    type: "session.update",
    session: {
      type: "realtime",
      model: "gpt-realtime-2.1-mini",
      output_modalities: ["audio"],
      instructions: "You are a concise voice assistant. Keep answers short.",
      audio: {
        output: {
          voice: "marin",
        },
      },
    },
  }));
};

channel.onmessage = (event) => {
  console.log(JSON.parse(event.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(),
});
Enter fullscreen mode Exit fullscreen mode

Bağlantı kurulduğunda model mikrofon kanalını dinler ve sesini pc.ontrack üzerinden döndürür. Oturum yapılandırması, metin girişleri ve araç sonuçları aynı oai-events veri kanalı üzerinden JSON olaylarıyla gönderilir.

Oturumu yapılandırma

Davranışı session nesnesiyle kontrol edersiniz. Sesli bir temsilci için temel yapılandırma:

{
  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"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Önemli alanlar:

  • instructions: sistem talimatıdır. Kişilik, sınırlar, iş kuralları ve kısa yanıt beklentisi burada tanımlanır.
  • output_modalities: konuşan aracı için ["audio"], sadece metin yanıtı için ["text"].
  • audio.output.voice: marin, cedar veya diğer desteklenen seslerden biri.
  • audio.input.turn_detection: kullanıcının konuşmayı bitirdiğini algılama yöntemi.
    • semantic_vad: anlamlı duraklamayı bekler, daha doğal hissettirir.
    • server_vad: sessizliğe göre tetiklenir.

Arama devam ederken yeni bir session.update göndererek yapılandırmayı değiştirebilirsiniz. Yeniden bağlanmanız gerekmez.

Aracının eylem yapması için araçlar ekleyin

Sadece konuşan bir bot çoğu ürün akışı için yeterli değildir. Sipariş sorgulama, rezervasyon oluşturma veya envanter kontrolü için fonksiyon çağırma eklemeniz gerekir.

Gerçek Zamanlı API, platformun geri kalanıyla aynı fonksiyon çağırma modelini kullanır:

  1. Fonksiyonları oturumda tanımlayın.
  2. Modelin fonksiyon çağrısı oluşturmasını bekleyin.
  3. response.function_call_arguments.done olayını işleyin.
  4. Kendi kodunuzda fonksiyonu çalıştırın.
  5. Sonucu conversation.item.create ile modele geri gönderin.
  6. Yeni response.create ile konuşmayı devam ettirin.

Daha önce Chat API ile araç kullandıysanız zihinsel model aynıdır. Şema tarafını derinlemesine görmek için OpenAI fonksiyon çağırma rehberine, katı argüman yapıları için yapılandırılmış çıktılar yazısına bakabilirsiniz.

Daha karmaşık, çok adımlı sesli aracılar için OpenAI AgentKit daha üst seviye bir düzenleme katmanı sağlar.

Uygulamaya bağlamadan önce Apidog ile test edin

Yarı tamamlanmış bir uygulamada WebRTC, WebSocket, REST ve auth hatalarını aynı anda ayıklamak zordur. Önce API parçalarını izole test edin. Burada Apidog pratik bir test katmanı olarak iş görür.

1. Geçici token uç noktasını test edin

Uç nokta standart REST çağrısıdır:

POST https://api.openai.com/v1/realtime/client_secrets
Authorization: Bearer OPENAI_API_KEY
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

Gövde:

{
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1-mini"
  }
}
Enter fullscreen mode Exit fullscreen mode

Apidog'da bu isteği oluşturup gönderin. Yanıtta ek_ ile başlayan geçici tokenı görmelisiniz. Bu test, WebRTC koduna geçmeden önce anahtarınızın ve hesap erişiminizin doğru olduğunu doğrular.

Aynı yaklaşımı OpenAI'ın diğer REST yüzeylerini test ederken de kullanabilirsiniz; örneğin Yanıtlar API'si.

2. WebSocket mesaj akışını test edin

Apidog WebSocket istemcisiyle şu adrese bağlanın:

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

Başlık:

Authorization: Bearer OPENAI_API_KEY
Enter fullscreen mode Exit fullscreen mode

Ardından mesajları tek tek gönderin:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1-mini",
    "output_modalities": ["text"],
    "instructions": "You are a concise API support agent."
  }
}
Enter fullscreen mode Exit fullscreen mode 
{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Explain WebRTC in one sentence."
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode 
{
  "type": "response.create"
}
Enter fullscreen mode Exit fullscreen mode

Sunucu olaylarını okunabilir bir panelde görmek, olay sırasını ve payload yapısını netleştirir. Mesajları ekip içinde örnek olarak da saklayabilirsiniz. Zaten API test stratejileri uyguluyorsanız, bu testleri aynı sürece ekleyin.

Apidog'u kullanmak isterseniz buradan indirebilirsiniz.

Faturayı kontrol altında tutma

Ses çıkışı en pahalı kısım olduğu için şu kontrolleri ekleyin:

  • Kısa yanıt talimatı verin. Örneğin: Yanıtları 1-2 cümleyle sınırla.
  • Üretimde anlık görüntü sabitleyin. gpt-realtime-mini-2025-12-15 değişmez; gpt-realtime-mini değişebilir.
  • semantic_vad kullanın. Daha az yanlış kesinti, daha az boşa üretilen yanıt demektir.
  • Sabit sistem talimatlarını önbelleğe alın. Önbelleğe alınmış giriş daha ucuzdur.
  • Boş oturumları kapatın. Kullanıcı aktif değilse bağlantıyı temizleyin.
  • Araç çağrısından önce onay alın. Gereksiz konuşma ve gereksiz backend işlemlerini azaltır.

Yaygın hatalar ve düzeltmeler

Hata Olası neden Çözüm
401 Unauthorized Yanlış API anahtarı veya süresi dolmuş geçici token Her oturum için yeni geçici token üretin
Model not found Yanlış model kimliği gpt-realtime-2.1-mini kullanın; gpt-realtime-mini-2.1 değil
Tarayıcıda ses yok pc.ontrack bağlanmadı veya sayfa HTTPS/localhost değil <audio autoplay> ekleyin, HTTPS/localhost kullanın
Model kullanıcının üstüne konuşuyor Turn detection uygun değil semantic_vad kullanın
WebSocket bağlanıyor ama yanıt yok response.create gönderilmedi Mesajdan sonra mutlaka response.create gönderin
Beta başlığı hatası Eski OpenAI-Beta başlığı kullanılıyor GA uç noktasında bu başlığı kaldırın

SSS

gpt-realtime-2.1-mini, gpt-realtime-mini ile aynı mı?

Etkili olarak evet. gpt-realtime-2.1-mini sürüm numaralı kimliktir. gpt-realtime-mini ise en son anlık görüntüye, şu anda gpt-realtime-mini-2025-12-15, işaret eden takma addır.

Sadece transkripsiyon için kullanabilir miyim?

Gerçek Zamanlı API, düşük gecikmeli iki yönlü konuşma için tasarlanmıştır. Tek seferlik transkripsiyon için OpenAI'ın özel transkripsiyon modelleri daha uygun olabilir.

WebRTC şart mı?

Hayır. Sunucu tarafı prototipler ve medya pipeline'ları için WebSocket yeterlidir. Tarayıcı veya mobil uygulama mikrofonu doğrudan kullanıyorsa WebRTC daha uygundur.

Hangi sesi seçmeliyim?

marin ve cedar, en yeni ve en doğal seslerdir. Belirli bir tını istiyorsanız alloy, ash, ballad, coral, echo, sage, shimmer veya verse kullanabilirsiniz.

Nasıl faturalandırılır?

Modaliteye göre token başına faturalandırılır. Mini için oranlar: 1M metin girişi başına $0.60, 1M ses girişi başına $10 ve 1M ses çıkışı başına $20. En büyük maliyet kalemi genellikle ses çıkışıdır.

Fonksiyon çağırabilir mi?

Evet. Gerçek Zamanlı API aynı fonksiyon çağırma sözleşmesini kullanır. Böylece sesli aracı sipariş sorgulayabilir, envanter kontrol edebilir veya konuşma sırasında backend eylemleri tetikleyebilir.

Sırada ne var?

Artık temel döngü hazır:

  1. Doğru model kimliğini seçin.
  2. WebSocket ile metin tabanlı prototip oluşturun.
  3. output_modalities değerini sese geçirin.
  4. Tarayıcı veya mobil istemci için WebRTC kullanın.
  5. Oturumu instructions, voice ve turn_detection ile şekillendirin.
  6. Gerekirse fonksiyon çağırma ekleyin.
  7. Üretime almadan önce REST ve WebSocket parçalarını Apidog ile izole test edin.

Başlamak için önce yalnızca metin döndüren WebSocket örneğini çalıştırın. Erişimi doğruladıktan sonra sesi açın, ardından gerçek mikrofon için WebRTC'ye geçin. Üretimde anlık görüntü sabitleyin ve modeli kısa yanıt verecek şekilde yönlendirin.

Top comments (0)