Cara Menggunakan API GPT-Realtime-2.1-mini

Agen suara dulunya membutuhkan tiga bagian yang bergerak: pengenalan suara ke teks (speech-to-text), model bahasa, kemudian teks ke suara (text-to-speech). Setiap lompatan menambah latensi dan kehilangan nada. OpenAI’s Realtime API menggabungkan itu menjadi satu model suara ke suara, dan gpt-realtime-2.1-mini adalah tingkatan yang lebih murah dan lebih cepat dari keluarga tersebut. Ia mendengarkan audio, berpikir, dan merespons melalui satu koneksi streaming.

Panduan ini menunjukkan cara memanggilnya secara menyeluruh: ID model mana yang akan digunakan, cara menyambungkan melalui WebSocket dan WebRTC, cara membentuk sesi, dan cara menguji keseluruhan hal dengan Apidog sebelum Anda memasangnya ke dalam aplikasi. Semua yang ada di sini mengacu pada panduan resmi OpenAI Realtime.

Pertama, pastikan nama modelnya benar

Penamaan sering membingungkan, jadi mari kita jelaskan sebelum kode apa pun. Ada dua pengenal untuk model mini yang sama:

• gpt-realtime-2.1-mini: ID berversi. Ini adalah apa yang muncul di halaman harga OpenAI dan mengikat Anda ke generasi 2.1.
• gpt-realtime-mini: alias keluarga. Ini selalu menunjuk ke snapshot terbaru, saat ini gpt-realtime-mini-2025-12-15.

Snapshot memungkinkan Anda mengunci perilaku dalam produksi:

Gunakan alias saat Anda membangun, lalu patok snapshot ber tanggal sebelum Anda merilisnya agar pembaruan model tidak pernah mengubah perilaku agen Anda dalam semalam.

Apa yang dilakukan gpt-realtime-2.1-mini

Ini adalah model suara ke suara. Anda mengalirkan audio masuk, dan ia mengalirkan audio kembali dengan intonasi alami, tanpa langkah transkripsi atau TTS terpisah. Ini juga menangani teks, sehingga Anda dapat mencampur input ketikan dan output lisan dalam sesi yang sama.

Berikut adalah lembar spesifikasi dari halaman model:

marin dan cedar adalah suara terbaru dan eksklusif untuk Realtime API; OpenAI merekomendasikannya untuk keluaran yang paling alami. Suara yang lebih lama masih berfungsi jika Anda menginginkan timbre tertentu.

Tingkatan "mini" mengorbankan sedikit kedalaman penalaran untuk latensi yang lebih rendah dan biaya yang jauh lebih murah. Untuk sebagian besar bot dukungan, alur pemesanan, dan antarmuka suara, ini adalah default yang tepat. Raih gpt-realtime-2.1 penuh hanya ketika percakapan membutuhkan penalaran yang lebih berat.

Berapa biayanya

Mini kira-kira sepertiga harga model penuh. Tarif token dari halaman harga:

Audio mendominasi tagihan, dan pengungkit biaya terbesar adalah seberapa banyak agen Anda berbicara. Agen yang berbicara 35 detik per menit biayanya kira-kira dua kali lipat dari yang berbicara 15 detik per menit. Biaya per menit dunia nyata untuk mini berkisar antara $0,06 hingga $0,15 tergantung pada keragaman, jadi instruksikan model Anda untuk ringkas dalam instruksi dan Anda akan langsung mengurangi tagihan. Tarif dapat berubah, jadi konfirmasikan dengan halaman harga langsung sebelum Anda memperkirakan.

Prasyarat

Anda membutuhkan tiga hal:

1. Kunci API OpenAI dengan akses Realtime, diatur sebagai OPENAI_API_KEY.
2. Node.js 18+ untuk contoh server (paket ws untuk WebSocket mentah, atau SDK resmi openai).
3. Untuk audio browser, halaman yang disajikan melalui HTTPS atau localhost agar getUserMedia berfungsi.

Satu aturan sebelum Anda menyentuh browser: jangan pernah mengirimkan kunci API asli Anda ke klien. Aplikasi browser dan seluler menggunakan token ephemeral berumur pendek sebagai gantinya. Lebih lanjut tentang itu di bawah.

Pilih metode koneksi

Model mini mendukung tiga transport. Pilih berdasarkan lokasi audio Anda.

Kebanyakan orang mulai dengan WebSocket untuk prototipe sisi server, lalu beralih ke WebRTC untuk klien yang sebenarnya. Mari kita lakukan keduanya.

Mulai Cepat 1: WebSocket dari server Anda

WebSocket adalah cara tercepat untuk melihat model merespons. Titik akhir adalah URL tunggal dengan model di string kueri:

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

Karena ini adalah antarmuka GA, Anda mengautentikasi dengan header `Authorization: Bearer` biasa dan Anda tidak lagi membutuhkan header `OpenAI-Beta` lama. Berikut adalah "hello world" teks-masuk, teks-keluar sehingga Anda dapat menguji tanpa mikrofon:

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. Konfigurasi sesi
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      type: "realtime",
      model: "gpt-realtime-2.1-mini",
      output_modalities: ["text"],
      instructions: "Anda adalah agen dukungan API yang ringkas. Berikan jawaban singkat.",
    },
  }));

  // 2. Tambahkan pesan pengguna
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [{ type: "input_text", text: "Apa itu permintaan idempotent?" }],
    },
  }));

  // 3. Minta respons
  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();
});

Alurnya selalu sama: konfigurasi, tambahkan input, minta respons, dengarkan delta. Acara server mengalir kembali sebagai JSON. Yang paling Anda pedulikan:

• session.created / session.updated: konfigurasi Anda diterima
• response.output_text.delta: sepotong teks
• response.output_audio.delta: sepotong audio base64
• response.output_audio_transcript.delta: transkrip apa yang dikatakan model
• response.done: giliran selesai

Untuk beralih dari teks ke suara, alihkan output_modalities ke ["audio"] dan tambahkan konfigurasi audio (bagian selanjutnya). Audio tiba di acara response.output_audio.delta sebagai potongan PCM base64 yang Anda dekode dan putar.

Mulai Cepat 2: WebRTC di browser

Untuk aplikasi suara yang nyata, browser menangkap mikrofon dan memutar balasan secara langsung, yang menjaga latensi tetap rendah. Tangkapannya adalah autentikasi: Anda tidak dapat mengekspos kunci API Anda, jadi server Anda pertama-tama membuat token berumur pendek.

Langkah 1: buat token ephemeral di server Anda. Panggil titik akhir rahasia-klien dengan kunci asli Anda:

// sisi server
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(); // kunci ephemeral, dimulai dengan "ek_"

Kirim value ke browser. Ini kedaluwarsa dengan cepat, jadi kebocoran berisiko rendah.

Langkah 2: sambungkan dari browser dengan WebRTC. Anda menangkap mikrofon, membuka saluran data untuk acara, dan bertukar SDP dengan titik akhir /v1/realtime/calls:

// sisi browser: `EPHEMERAL_KEY` berasal dari server Anda
const pc = new RTCPeerConnection();

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

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

// acara mengalir melalui saluran data
const channel = pc.createDataChannel("oai-events");
channel.onmessage = (e) => console.log(JSON.parse(e.data));

// jabat tangan SDP
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() });

Setelah koneksi aktif, model mendengarkan di jalur mikrofon dan berbicara melalui pc.ontrack. Anda mengirim konfigurasi dan teks melalui saluran data oai-events yang sama menggunakan acara JSON persis dari contoh WebSocket.

Membentuk sesi

Objek session adalah tempat Anda mengontrol perilaku. Ini adalah versi audio-penuh dari apa yang Anda lihat di atas:

{
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2.1-mini",
    output_modalities: ["audio"],
    instructions: "Anda adalah asisten pemesanan yang ramah. Konfirmasi detail sebelum bertindak.",
    audio: {
      input: {
        format: { type: "audio/pcm", rate: 24000 },
        turn_detection: { type: "semantic_vad" },
      },
      output: {
        format: { type: "audio/pcm", rate: 24000 },
        voice: "marin",
      },
    },
  },
}

Bidang yang penting:

• instructions: prompt sistem Anda. Atur persona, batasan, dan "bersikaplah singkat" jika Anda peduli biaya.
• output_modalities: ["audio"] untuk agen berbicara, ["text"] untuk bot hanya transkrip.
• audio.output.voice: pilih dari sepuluh suara; marin atau cedar terdengar paling alami.
• audio.input.turn_detection: bagaimana model memutuskan Anda telah berhenti berbicara. semantic_vad menunggu jeda alami dalam makna; server_vad terpicu saat hening. Deteksi semantik lebih jarang mengganggu dan terasa lebih mulus dalam percakapan.

Ubah bidang apa pun di tengah panggilan dengan mengirimkan session.update lainnya. Anda tidak perlu menyambung kembali.

Menambahkan alat agar agen dapat bertindak

Agen suara yang hanya bisa mengobrol hanyalah demo. Untuk memesan meja atau memeriksa pesanan, model membutuhkan alat. Realtime menggunakan kontrak pemanggilan fungsi yang sama dengan platform lainnya: Anda mendeklarasikan fungsi dalam sesi, model mengeluarkan panggilan, Anda menjalankannya, dan Anda memberikan hasilnya kembali. Jika Anda pernah menyambungkan alat ke API obrolan sebelumnya, ini adalah model mental yang sama; panduan kami tentang pemanggilan fungsi OpenAI membahas skema secara mendalam, dan output terstruktur membantu saat Anda membutuhkan argumen yang sesuai dengan bentuk yang ketat.

Deklarasikan alat di dalam sesi, lalu tangani peristiwa response.function_call_arguments.done, jalankan kode Anda, dan posting conversation.item.create dengan hasilnya sebelum response.create berikutnya. Untuk sesuatu yang lebih rumit daripada beberapa fungsi, OpenAI’s AgentKit memberi Anda cara tingkat tinggi untuk mengatur agen suara multi-langkah.

Uji titik akhir dengan Apidog sebelum Anda membangun

Anda tidak ingin men-debug panggilan REST dan jabat tangan WebSocket dengan membaca log konsol di aplikasi yang belum selesai. Uji bagian-bagiannya secara terpisah terlebih dahulu. Di sinilah Apidog mendapatkan tempatnya dalam alur kerja realtime.

Dua hal yang patut divalidasi sebelum Anda menulis kode klien:

1. Titik akhir token. POST https://api.openai.com/v1/realtime/client_secrets adalah panggilan REST biasa. Buat permintaan di Apidog, tambahkan header Authorization: Bearer Anda, masukkan badan JSON dengan ID model Anda, dan kirimkan. Anda akan segera melihat token ek_ dan masa berlakunya, sehingga Anda tahu kunci dan akses akun Anda baik-baik saja bahkan sebelum WebRTC terlibat. Ini adalah pendekatan yang sama yang akan Anda gunakan untuk menguji permukaan REST OpenAI lainnya, seperti Responses API.
2. Alur pesan WebSocket. Apidog memiliki klien WebSocket, sehingga Anda dapat membuka koneksi ke wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini, menambahkan header autentikasi, dan secara manual mengirim pesan session.update, conversation.item.create, dan response.create satu per satu. Mengamati peristiwa server kembali dalam panel yang mudah dibaca membuat urutan peristiwa menjadi jelas, dan Anda dapat menyimpan pesan sebagai contoh untuk tim Anda. Jika Anda sudah mengandalkan strategi pengujian API yang solid, ini sangat cocok.

Menguji lapisan transport sendiri berarti ketika ada sesuatu yang rusak di aplikasi, Anda sudah tahu itu bukan kontrak API. Unduh Apidog jika Anda ingin mengikuti.

Jaga tagihan tetap terkontrol

Keluaran audio adalah bagian yang mahal, jadi beberapa kebiasaan akan bermanfaat:

• Instruksikan model untuk singkat. "Jaga jawaban satu atau dua kalimat" dalam instruksi secara langsung mengurangi token keluaran audio.
• Patok snapshot dalam produksi. gpt-realtime-mini-2025-12-15 tidak akan berubah; alias gpt-realtime-mini bisa.
• Gunakan semantic_vad. Lebih sedikit interupsi palsu berarti lebih sedikit setengah-respons yang terbuang yang Anda bayar.
• Cache prompt sistem Anda. Masukan yang di-cache adalah $0,30 per 1M dibandingkan $0,60 untuk masukan teks baru, jadi blok instruksi yang stabil lebih murah setiap giliran.
• Tutup sesi yang tidak aktif. Koneksi terbuka dengan pengguna yang tidak aktif masih merupakan sesi yang mungkin dikenakan biaya kepada Anda.

Kesalahan umum dan perbaikannya

• 401 Unauthorized: kuncinya salah, atau Anda mengirim token ephemeral yang kedaluwarsa. Kunci ephemeral sengaja berumur pendek; buat yang baru per sesi.
• Model not found: periksa ID persisnya. Itu gpt-realtime-2.1-mini, bukan gpt-realtime-mini-2.1.
• Tidak ada audio di browser: Anda mungkin tidak melampirkan aliran jarak jauh di pc.ontrack, atau halaman tidak berada di HTTPS/localhost sehingga mikrofon tidak pernah terbuka.
• Model tidak berhenti berbicara saat pengguna berbicara: alihkan turn_detection ke semantic_vad dan konfirmasikan bahwa jalur mikrofon mencapai koneksi.
• Mengirimkan header beta: titik akhir GA tidak memerlukan OpenAI-Beta: realtime=v1. Hapus itu.

FAQ

Apakah gpt-realtime-2.1-mini sama dengan gpt-realtime-mini? Secara efektif ya. gpt-realtime-2.1-mini adalah ID versi, gpt-realtime-mini adalah alias yang menunjuk ke snapshot terbaru (gpt-realtime-mini-2025-12-15). Gunakan alias untuk membangun, patok snapshot untuk rilis.

Bisakah saya menggunakannya untuk transkripsi biasa alih-alih agen suara? Realtime API dibangun untuk pidato-ke-pidato interaktif. Untuk transkripsi satu kali, model transkripsi khusus OpenAI lebih cocok. Gunakan model mini realtime ketika Anda membutuhkan percakapan dua arah dengan latensi rendah.

Apakah saya membutuhkan WebRTC, atau WebSocket sudah cukup? WebSocket cukup untuk pipeline sisi server dan prototipe cepat. Gunakan WebRTC ketika browser atau aplikasi seluler menangkap dan memutar audio secara langsung, karena ia menangani aliran media dan jitter untuk Anda.

Suara mana yang harus saya pilih? marin dan cedar adalah yang terbaru dan paling alami, dan keduanya eksklusif untuk Realtime API. Delapan suara lainnya (alloy, ash, ballad, coral, echo, sage, shimmer, verse) masih berfungsi jika Anda menginginkan suara tertentu.

Bagaimana ini ditagih? Per token, dibagi berdasarkan modalitas. Untuk mini: $0,60 per 1M masukan teks, $10 per 1M masukan audio, dan $20 per 1M keluaran audio. Keluaran audio adalah biaya yang dominan, jadi keragaman adalah pengungkit utama Anda.

Bisakah ia memanggil fungsi seperti model obrolan? Ya. Realtime menggunakan kontrak pemanggilan fungsi yang sama, sehingga agen suara dapat mencari pesanan, memeriksa inventaris, atau memicu tindakan di tengah percakapan.

Ke mana selanjutnya

Anda sekarang memiliki lingkaran penuh: ID model yang tepat, prototipe WebSocket, klien browser WebRTC, konfigurasi sesi, alat, dan cara untuk menguji setiap bagian di Apidog sebelum masuk ke produksi. Mulailah dengan contoh WebSocket hanya-teks untuk mengonfirmasi akses, alihkan output_modalities ke audio, lalu beralih ke WebRTC ketika Anda siap untuk mikrofon sungguhan. Patok snapshot, instruksikan model untuk ringkas, dan Anda akan memiliki agen suara latensi rendah yang tidak akan mengejutkan Anda pada faktur.