DEV Community

Cover image for Cách sử dụng API GPT-Realtime-2.1-mini
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Cách sử dụng API GPT-Realtime-2.1-mini

Các tác nhân giọng nói truyền thống thường phải ghép 3 bước: speech-to-text, mô hình ngôn ngữ, rồi text-to-speech. Mỗi bước thêm độ trễ và làm mất sắc thái hội thoại. Realtime API của OpenAI gom các bước này vào một luồng speech-to-speech duy nhất. Với gpt-realtime-2.1-mini, bạn có một lựa chọn rẻ hơn và nhanh hơn để nhận âm thanh, suy luận và trả lời bằng âm thanh qua một kết nối streaming.

Dùng thử Apidog hôm nay

Bài viết này hướng dẫn cách gọi model từ đầu đến cuối: chọn đúng model ID, kết nối qua WebSocket và WebRTC, cấu hình session, thêm tool/function calling, và kiểm thử với Apidog trước khi tích hợp vào ứng dụng. Nội dung bám theo hướng dẫn Realtime chính thức của OpenAI.

Trước tiên: chọn đúng tên mô hình

Có hai định danh dễ gây nhầm lẫn:

  • gpt-realtime-2.1-mini: ID có phiên bản. Đây là ID xuất hiện trên trang giá của OpenAI và khóa bạn vào thế hệ 2.1.
  • gpt-realtime-mini: alias của dòng mini. Nó trỏ đến snapshot mới nhất, hiện tại là gpt-realtime-mini-2025-12-15.

Các snapshot giúp bạn khóa hành vi trong production:

Định danh Nó trỏ đến cái gì
gpt-realtime-mini Snapshot mini mới nhất, tự động cập nhật
gpt-realtime-2.1-mini Mini thế hệ 2.1
gpt-realtime-mini-2025-12-15 Snapshot được ghim, hiện tại
gpt-realtime-mini-2025-10-06 Snapshot được ghim, trước đó

Cách dùng thực tế:

  1. Dùng gpt-realtime-mini khi thử nghiệm nhanh.
  2. Dùng gpt-realtime-2.1-mini nếu muốn khóa theo thế hệ 2.1.
  3. Ghim snapshot có ngày trước khi triển khai production để tránh thay đổi hành vi ngoài ý muốn.

Realtime model identifiers

gpt-realtime-2.1-mini làm gì?

gpt-realtime-2.1-mini là model speech-to-speech. Bạn stream âm thanh vào, model xử lý và stream âm thanh trả lại với ngữ điệu tự nhiên. Bạn không cần tự dựng pipeline speech-to-text hoặc text-to-speech riêng.

Model cũng hỗ trợ văn bản, nên trong cùng một session bạn có thể:

  • nhận input bằng giọng nói;
  • gửi thêm input bằng text;
  • trả lời bằng text hoặc audio;
  • lấy transcript của phần audio model đang nói.

Thông số từ trang model:

Thuộc tính Giá trị
Phương thức đầu vào Văn bản, hình ảnh, âm thanh
Phương thức đầu ra Văn bản, âm thanh
Cửa sổ ngữ cảnh 32.000 token
Đầu ra tối đa 4.096 token
Kết nối WebRTC, WebSocket, SIP
Giọng nói alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar

marin và cedar là các giọng mới nhất, độc quyền của Realtime API. OpenAI khuyến nghị dùng chúng để có đầu ra tự nhiên nhất. Các giọng cũ hơn vẫn hoạt động nếu bạn cần một âm sắc cụ thể.

Bản mini đánh đổi một phần độ sâu suy luận để có độ trễ thấp hơn và chi phí thấp hơn. Với bot hỗ trợ, đặt lịch, nhận đơn hàng, hoặc voice UI, đây thường là lựa chọn mặc định. Chỉ dùng gpt-realtime-2.1 đầy đủ khi cuộc hội thoại cần suy luận phức tạp hơn.

Chi phí

Theo trang giá, bản mini rẻ hơn đáng kể so với model đầy đủ:

Mô hình Đầu vào văn bản Đầu vào đã cache Đầu vào âm thanh Đầu ra âm thanh
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

Phần tốn kém nhất thường là đầu ra âm thanh. Một agent nói 35 giây mỗi phút có thể tốn gần gấp đôi agent chỉ nói 15 giây mỗi phút.

Chi phí thực tế mỗi phút cho bản mini thường dao động khoảng $0.06 đến $0.15, tùy agent nói nhiều hay ít. Vì giá có thể thay đổi, hãy kiểm tra lại trang giá trực tiếp trước khi dự báo chi phí.

Điều kiện tiên quyết

Bạn cần:

  1. OpenAI API key có quyền truy cập Realtime, đặt trong biến môi trường OPENAI_API_KEY.
  2. Node.js 18+ cho ví dụ server.
  3. Gói ws nếu dùng WebSocket thô.
  4. Trang chạy qua HTTPS hoặc localhost nếu dùng getUserMedia trong trình duyệt.

Cài gói WebSocket:

npm install ws
Enter fullscreen mode Exit fullscreen mode

Quy tắc quan trọng:

Không bao giờ gửi API key thật xuống browser hoặc mobile client.

Với browser/mobile, hãy tạo ephemeral token ngắn hạn từ server, rồi đưa token đó cho client.

Chọn phương thức kết nối

gpt-realtime-2.1-mini hỗ trợ WebRTC, WebSocket và SIP.

Giao thức Dùng khi Xác thực
WebRTC Browser hoặc mobile app thu/phát audio trực tiếp Ephemeral client secret
WebSocket Server của bạn xử lý audio thô hoặc cần prototype nhanh API key phía server
SIP Kết nối hệ thống điện thoại API key

Khuyến nghị triển khai:

  1. Bắt đầu với WebSocket để xác nhận model, auth và event flow.
  2. Chuyển sang WebRTC khi cần mic, loa và độ trễ thấp trong browser/mobile.
  3. Dùng SIP nếu bạn tích hợp vào hệ thống thoại.

Bắt đầu nhanh 1: WebSocket từ server

Endpoint WebSocket:

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

Với GA endpoint, bạn dùng header Authorization: Bearer ... thông thường. Không cần header beta cũ OpenAI-Beta.

Ví dụ dưới đây gửi text và nhận text để kiểm tra nhanh mà không cần microphone:

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. Cấu hình 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. Thêm message của user
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [
        {
          type: "input_text",
          text: "What is an idempotent request?",
        },
      ],
    },
  }));

  // 3. Yêu cầu model trả lời
  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();
  }
});
Enter fullscreen mode Exit fullscreen mode

Luồng cơ bản luôn là:

  1. session.update: cấu hình session.
  2. conversation.item.create: thêm input.
  3. response.create: yêu cầu model phản hồi.
  4. Lắng nghe các event delta trả về.

Các event quan trọng:

Event Ý nghĩa
session.created Session được tạo
session.updated Cấu hình session đã được cập nhật
response.output_text.delta Một đoạn text trả về
response.output_audio.delta Một đoạn audio base64
response.output_audio_transcript.delta Transcript của phần audio model đang nói
response.done Lượt phản hồi đã hoàn tất

Để chuyển sang audio output, đổi:

output_modalities: ["text"]
Enter fullscreen mode Exit fullscreen mode

thành:

output_modalities: ["audio"]
Enter fullscreen mode Exit fullscreen mode

và thêm cấu hình audio trong session.

Bắt đầu nhanh 2: WebRTC trong browser

Với ứng dụng thoại thực tế, WebRTC phù hợp hơn vì browser có thể:

  • lấy âm thanh từ microphone;
  • phát audio trả về;
  • xử lý media streaming với độ trễ thấp.

Nhưng browser không được giữ API key thật. Bạn cần server tạo ephemeral token trước.

Bước 1: Tạo ephemeral token trên server 

// 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_"
Enter fullscreen mode Exit fullscreen mode

Gửi value này xuống browser. Token có thời hạn ngắn, nên rủi ro thấp hơn nhiều so với việc lộ API key thật.

Bước 2: Kết nối WebRTC từ browser

HTML tối thiểu:

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

JavaScript:

// browser side: EPHEMERAL_KEY được lấy từ server
const pc = new RTCPeerConnection();

// Phát audio từ model
pc.ontrack = (e) => {
  document.getElementById("audio").srcObject = e.streams[0];
};

// Gửi microphone lên model
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
pc.addTrack(mic.getTracks()[0]);

// Event JSON đi qua 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(),
});
Enter fullscreen mode Exit fullscreen mode

Sau khi kết nối thành công:

  • model nghe microphone qua WebRTC track;
  • model trả audio qua pc.ontrack;
  • bạn gửi event JSON qua data channel oai-events.

Bạn có thể gửi cùng loại event như WebSocket:

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.",
  },
}));
Enter fullscreen mode Exit fullscreen mode

Định hình session

session.update là nơi bạn kiểm soát hành vi của agent.

Ví dụ session audio đầy đủ:

{
  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

Các trường nên cấu hình rõ:

Trường Dùng để làm gì
instructions Định nghĩa vai trò, quy tắc, giới hạn, độ dài câu trả lời
output_modalities ["audio"] cho voice agent, ["text"] cho transcript bot
audio.output.voice Chọn giọng nói, ví dụ marin hoặc cedar
audio.input.turn_detection Quyết định khi nào user đã nói xong

Với turn detection:

  • semantic_vad: chờ điểm dừng tự nhiên theo ngữ nghĩa, thường ít ngắt lời hơn.
  • server_vad: kích hoạt dựa trên khoảng im lặng.

Bạn có thể gửi session.update nhiều lần trong cùng một kết nối để đổi instruction, voice hoặc cấu hình khác mà không cần reconnect.

Thêm công cụ để agent có thể hành động

Voice agent chỉ trò chuyện thì mới là demo. Để đặt bàn, kiểm tra đơn hàng hoặc tra cứu dữ liệu, model cần tool/function.

Realtime dùng cùng mô hình function calling như các phần khác của nền tảng:

  1. Khai báo tool trong session.
  2. Model phát ra function call.
  3. Server của bạn chạy function thật.
  4. Bạn gửi kết quả ngược lại vào conversation.
  5. Gọi response.create để model tiếp tục trả lời user.

Nếu bạn đã từng tích hợp tool với Chat API, cách tư duy gần như giống nhau. Có thể xem thêm hướng dẫn về gọi hàm của OpenAI và structured outputs khi cần đối số có schema chặt chẽ.

Luồng xử lý tool thường là:

ws.on("message", async (raw) => {
  const event = JSON.parse(raw.toString());

  if (event.type === "response.function_call_arguments.done") {
    const args = JSON.parse(event.arguments);

    // Chạy logic thật của bạn
    const result = await lookupOrder(args.order_id);

    // Gửi output của function trở lại conversation
    ws.send(JSON.stringify({
      type: "conversation.item.create",
      item: {
        type: "function_call_output",
        call_id: event.call_id,
        output: JSON.stringify(result),
      },
    }));

    // Yêu cầu model tiếp tục trả lời
    ws.send(JSON.stringify({
      type: "response.create",
    }));
  }
});
Enter fullscreen mode Exit fullscreen mode

Với workflow nhiều bước, AgentKit của OpenAI là lựa chọn cấp cao hơn để điều phối agent.

Kiểm thử endpoint với Apidog trước khi viết client

Đừng debug REST call, WebSocket handshake và audio pipeline cùng lúc trong một app chưa hoàn thiện. Hãy kiểm thử từng lớp trước bằng Apidog.

1. Kiểm thử endpoint tạo token

Endpoint:

POST https://api.openai.com/v1/realtime/client_secrets
Enter fullscreen mode Exit fullscreen mode

Body mẫu:

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

Header:

Authorization: Bearer YOUR_OPENAI_API_KEY
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

Trong Apidog, tạo request REST, thêm header và body trên, rồi gửi. Nếu thành công, bạn sẽ nhận token bắt đầu bằng ek_ và thời hạn của nó.

Cách này giúp bạn xác nhận:

  • API key đúng;
  • tài khoản có quyền truy cập Realtime;
  • body request hợp lệ;
  • lỗi không nằm ở WebRTC client.

Bạn có thể dùng cùng cách kiểm thử cho các REST API khác, ví dụ Responses API.

2. Kiểm thử WebSocket event flow

Kết nối WebSocket:

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

Header:

Authorization: Bearer YOUR_OPENAI_API_KEY
Enter fullscreen mode Exit fullscreen mode

Sau đó gửi lần lượt:

{
  "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 idempotency in one sentence."
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode 
{
  "type": "response.create"
}
Enter fullscreen mode Exit fullscreen mode

Khi nhìn event trả về trong WebSocket client của Apidog, bạn sẽ thấy rõ thứ tự session.updated, response.output_text.delta, response.done, v.v.

Việc này phù hợp với quy trình kiểm thử API có chiến lược: xác nhận contract trước, rồi mới tích hợp vào UI.

Nếu muốn làm theo, bạn có thể tải Apidog.

Kiểm soát chi phí

Một số thói quen giúp giảm chi phí:

  • Yêu cầu model trả lời ngắn. Thêm instruction như: Keep answers under two sentences.
  • Ghim snapshot trong production. Dùng gpt-realtime-mini-2025-12-15 thay vì alias tự cập nhật.
  • Dùng semantic_vad. Ít ngắt lời sai hơn, ít tạo phản hồi nửa chừng hơn.
  • Giữ system prompt ổn định để tận dụng cached input. Input đã cache rẻ hơn input text mới.
  • Đóng session không hoạt động. Đừng giữ kết nối mở khi user đã rời đi.
  • Theo dõi độ dài audio output. Agent càng nói nhiều, chi phí càng tăng.

Instruction mẫu để giảm verbosity:

You are a voice support agent. Answer in one or two short sentences. Ask one question at a time.
Enter fullscreen mode Exit fullscreen mode

Lỗi thường gặp và cách khắc phục

Lỗi Cách xử lý
401 Unauthorized Kiểm tra API key, quyền truy cập Realtime, hoặc ephemeral token đã hết hạn
Model not found Dùng đúng ID: gpt-realtime-2.1-mini, không phải gpt-realtime-mini-2.1
Không có audio trong browser Kiểm tra pc.ontrack, thẻ <audio autoplay>, HTTPS/localhost và quyền microphone
Model nói chồng lên user Dùng semantic_vad và xác nhận mic track đã được add vào connection
WebSocket không kết nối Kiểm tra URL, header Authorization, network/proxy và model query param
Gửi header beta cũ Bỏ OpenAI-Beta: realtime=v1 với GA endpoint

FAQ

gpt-realtime-2.1-mini có giống gpt-realtime-mini không?

Gần như có. gpt-realtime-2.1-mini là ID có phiên bản. gpt-realtime-mini là alias trỏ đến snapshot mới nhất, hiện tại là gpt-realtime-mini-2025-12-15.

Dùng alias khi phát triển nhanh. Ghim snapshot khi triển khai production.

Tôi có thể dùng nó chỉ để speech-to-text không?

Realtime API được tối ưu cho hội thoại hai chiều speech-to-speech độ trễ thấp. Nếu bạn chỉ cần chuyển giọng nói thành văn bản một lần, các model speech-to-text chuyên dụng của OpenAI phù hợp hơn.

WebSocket có đủ không, hay bắt buộc dùng WebRTC?

WebSocket đủ cho server-side pipeline và prototype nhanh. Dùng WebRTC khi browser hoặc mobile app thu/phát audio trực tiếp.

Nên chọn giọng nói nào?

marin và cedar là các giọng mới nhất và tự nhiên nhất trong Realtime API. Các giọng alloy, ash, ballad, coral, echo, sage, shimmer, verse vẫn dùng được nếu bạn cần âm sắc khác.

Chi phí được tính thế nào?

Theo token và theo modality. Với mini:

  • input text: $0.60 / 1M token;
  • cached input: $0.30 / 1M token;
  • input audio: $10 / 1M token;
  • output audio: $20 / 1M token.

Đầu ra audio thường là phần chi phí lớn nhất.

Model có gọi function được không?

Có. Realtime dùng cùng hợp đồng function calling. Voice agent có thể gọi function để tra cứu đơn hàng, kiểm tra tồn kho, đặt lịch hoặc kích hoạt hành động trong lúc hội thoại.

Tiếp theo nên làm gì?

Bạn đã có đủ các phần để dựng một voice agent với gpt-realtime-2.1-mini:

  1. Xác nhận model ID.
  2. Prototype bằng WebSocket text-only.
  3. Chuyển output_modalities sang audio.
  4. Cấu hình voice, VAD và instruction.
  5. Dùng WebRTC cho browser/mobile.
  6. Thêm tool/function nếu agent cần hành động.
  7. Kiểm thử REST và WebSocket trong Apidog trước khi đưa vào app.

Khi lên production, hãy ghim snapshot, giữ câu trả lời ngắn, dùng ephemeral token cho client, và đóng session không hoạt động để kiểm soát chi phí.

Top comments (0)