Blog

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

Cách sử dụng API gpt-realtime-2.1-mini: ID mô hình phù hợp, các kết nối WebSocket và WebRTC, cấu hình phiên, giọng nói, giá cả và kiểm tra các điểm cuối trong Apidog.

Ashley Innocent

Ashley Innocent

8 tháng 7 2026

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

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Các tác nhân giọng nói trước đây cần ba thành phần chuyển động: chuyển giọng nói thành văn bản, một mô hình ngôn ngữ, sau đó chuyển văn bản thành giọng nói. Mỗi bước nhảy đều làm tăng độ trễ và mất đi sắc thái. API Realtime của OpenAI đã hợp nhất chúng thành một mô hình chuyển giọng nói thành giọng nói duy nhất, và gpt-realtime-2.1-mini là phiên bản rẻ hơn, nhanh hơn trong dòng sản phẩm đó. Nó lắng nghe âm thanh, suy nghĩ và phản hồi qua một kết nối truyền trực tuyến duy nhất.

Hướng dẫn này chỉ cho bạn cách gọi nó từ đầu đến cuối: ID mô hình nào để sử dụng, cách kết nối qua WebSocket và WebRTC, cách định hình một phiên làm việc, và cách kiểm tra toàn bộ với Apidog trước khi bạn tích hợp nó vào một ứng dụng. Mọi thứ ở đây đều tương ứng với hướng dẫn Realtime chính thức của OpenAI.

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

Cách đặt tên có thể khiến mọi người bối rối, vì vậy hãy làm rõ điều này trước khi đi vào mã. Có hai định danh cho cùng một mô hình mini:

Các bản chụp cho phép bạn khóa hành vi trong môi trường sản xuất:

Định danh Nó trỏ đến cái gì
gpt-realtime-mini Bản chụp 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 Bản chụp được ghim (hiện tại)
gpt-realtime-mini-2025-10-06 Bản chụp được ghim (trước đó)

Sử dụng biệt danh trong quá trình xây dựng, sau đó ghim một bản chụp có ngày trước khi triển khai để bản cập nhật mô hình không bao giờ làm thay đổi hành vi của tác nhân của bạn một cách bất ngờ.

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

Đây là một mô hình chuyển giọng nói thành giọng nói. Bạn truyền âm thanh vào, và nó truyền âm thanh trở lại với ngữ điệu tự nhiên, không cần bước chuyển đổi giọng nói thành văn bản hoặc chuyển văn bản thành giọng nói riêng biệt. Nó cũng xử lý văn bản, vì vậy bạn có thể kết hợp nhập liệu bằng văn bản và xuất giọng nói trong cùng một phiên.

Đây là bảng thông số kỹ thuật từ trang mô hình:

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à những giọng nói mới nhất và độc quyền của Realtime API; OpenAI khuyến nghị sử dụng chúng để có đầu ra tự nhiên nhất. Các giọng nói cũ hơn vẫn hoạt động nếu bạn muốn một âm sắc cụ thể.

Phiên bản "mini" đánh đổi một chút chiều sâu suy luận để đạt được độ trễ thấp hơn và chi phí thấp hơn đáng kể. Đối với hầu hết các bot hỗ trợ, quy trình nhận đơn hàng và giao diện giọng nói, đây là lựa chọn mặc định phù hợp. Chỉ nên sử dụng phiên bản đầy đủ `gpt-realtime-2.1` khi cuộc hội thoại cần suy luận phức tạp hơn.

Chi phí

Phiên bản Mini có giá khoảng một phần ba so với mô hình đầy đủ. Giá token từ trang giá:

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 (full) $4.00 / 1M $0.40 / 1M $32 / 1M $64 / 1M

Âm thanh chiếm phần lớn chi phí, và yếu tố chi phí lớn nhất là tác nhân của bạn nói bao nhiêu. Một tác nhân nói 35 giây mỗi phút có chi phí gấp đôi so với tác nhân nói 15 giây mỗi phút. Chi phí thực tế mỗi phút cho phiên bản mini dao động khoảng $0.06 đến $0.15 tùy thuộc vào mức độ nói nhiều, vì vậy hãy chỉ dẫn mô hình của bạn nói ngắn gọn và bạn sẽ giảm chi phí trực tiếp. Tỷ giá thay đổi, vì vậy hãy xác nhận với trang giá trực tiếp trước khi dự báo.

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

Bạn cần ba thứ:

  1. Khóa API OpenAI có quyền truy cập Realtime, được đặt là OPENAI_API_KEY.
  2. Node.js 18+ cho các ví dụ máy chủ (gói ws cho WebSocket thô, hoặc SDK openai chính thức).
  3. Đối với âm thanh trình duyệt, một trang được phục vụ qua HTTPS hoặc localhost để getUserMedia hoạt động.

Một quy tắc trước khi bạn thao tác với trình duyệt: không bao giờ gửi khóa API thực của bạn cho client. Các ứng dụng trình duyệt và di động sử dụng token tạm thời, có thời hạn ngắn thay thế. Thêm chi tiết bên dưới.

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

Mô hình mini hỗ trợ ba giao thức truyền tải. Chọn dựa trên nơi âm thanh của bạn được xử lý.

Giao thức truyền tải Sử dụng khi Xác thực
WebRTC Âm thanh được thu hoặc phát trong trình duyệt hoặc ứng dụng di động Mã bí mật client tạm thời
WebSocket Máy chủ của bạn đã xử lý âm thanh thô từ một đường ống media Khóa API (phía máy chủ)
SIP Bạn đang kết nối điện thoại hoặc hệ thống điện thoại Khóa API

Hầu hết mọi người bắt đầu với WebSocket để tạo nguyên mẫu phía máy chủ, sau đó chuyển sang WebRTC cho client thực. Chúng ta sẽ thực hiện cả hai.

Bắt đầu nhanh 1: WebSocket từ máy chủ của bạn

WebSocket là cách nhanh nhất để xem mô hình phản hồi. Điểm cuối là một URL duy nhất với mô hình trong chuỗi truy vấn:

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

Bởi vì đây là giao diện GA, bạn xác thực bằng tiêu đề Authorization: Bearer thông thường và bạn không còn cần tiêu đề OpenAI-Beta cũ nữa. Dưới đây là ví dụ "hello world" nhập văn bản, xuất văn bản để bạn có thể kiểm tra mà không cần micrô:

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();
});

Luồng hoạt động luôn giống nhau: cấu hình, thêm đầu vào, yêu cầu phản hồi, lắng nghe các bản cập nhật (deltas). Các sự kiện máy chủ được truyền về dưới dạng JSON. Những sự kiện bạn quan tâm nhất:

Để chuyển từ văn bản sang giọng nói, hãy đổi output_modalities thành ["audio"] và thêm cấu hình âm thanh (phần tiếp theo). Âm thanh đến trong các sự kiện response.output_audio.delta dưới dạng các đoạn PCM base64 mà bạn giải mã và phát.

Bắt đầu nhanh 2: WebRTC trong trình duyệt

Đối với một ứng dụng thoại thực tế, trình duyệt sẽ thu âm từ mic và phát phản hồi trực tiếp, giúp giữ độ trễ thấp. Vấn đề là xác thực: bạn không thể để lộ khóa API của mình, vì vậy máy chủ của bạn phải tạo một token có thời hạn ngắn trước.

Bước 1: tạo một token tạm thời trên máy chủ của bạn. Gọi điểm cuối client-secrets với khóa thực của bạ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_"

Gửi value đến trình duyệt. Nó hết hạn nhanh chóng, vì vậy rủi ro rò rỉ là thấp.

Bước 2: kết nối từ trình duyệt với WebRTC. Bạn thu âm từ mic, mở một kênh dữ liệu cho các sự kiện, và trao đổi SDP với điểm cuối /v1/realtime/calls:

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

Khi kết nối đã hoạt động, mô hình sẽ lắng nghe trên kênh mic và nói qua pc.ontrack. Bạn gửi cấu hình và văn bản qua cùng kênh dữ liệu oai-events bằng cách sử dụng chính xác các sự kiện JSON từ ví dụ WebSocket.

Định hình phiên làm việc

Đối tượng session là nơi bạn kiểm soát hành vi. Đây là phiên bản âm thanh đầy đủ của những gì bạn đã thấy ở trên:

{
  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",
      },
    },
  },
}

Các trường quan trọng:

Thay đổi bất kỳ trường nào trong cuộc gọi bằng cách gửi một session.update khác. Bạn không cần phải kết nối lại.

Thêm công cụ để tác nhân có thể hành động

Một tác nhân giọng nói chỉ có thể trò chuyện thì chỉ là một bản demo. Để đặt bàn hoặc kiểm tra đơn hàng, mô hình cần các công cụ. Realtime sử dụng cùng một hợp đồng gọi hàm như các phần khác của nền tảng: bạn khai báo các hàm trong phiên, mô hình phát ra một lệnh gọi, bạn chạy nó và bạn đưa kết quả trở lại. Nếu bạn đã từng tích hợp công cụ vào API trò chuyện trước đây, thì đây là cùng một mô hình tư duy; hướng dẫn của chúng tôi về gọi hàm của OpenAI bao gồm sơ đồ chi tiết, và đầu ra có cấu trúc giúp ích khi bạn cần các đối số phải khớp với một hình dạng nghiêm ngặt.

Khai báo các công cụ bên trong phiên, sau đó xử lý sự kiện response.function_call_arguments.done, chạy mã của bạn và đăng một conversation.item.create với kết quả trước response.create tiếp theo. Đối với bất kỳ điều gì phức tạp hơn một vài hàm, AgentKit của OpenAI cung cấp cho bạn một cách cao cấp hơn để điều phối các tác nhân giọng nói đa bước.

Kiểm tra các điểm cuối với Apidog trước khi xây dựng

Bạn không muốn gỡ lỗi một lệnh gọi REST và bắt tay WebSocket bằng cách đọc nhật ký console trong một ứng dụng chưa hoàn thiện. Hãy kiểm tra từng phần riêng lẻ trước. Đây là lúc Apidog phát huy tác dụng trong một quy trình làm việc thời gian thực.

Hai điều đáng để xác thực trước khi bạn viết mã client:

  1. Điểm cuối token. POST https://api.openai.com/v1/realtime/client_secrets là một lệnh gọi REST thông thường. Tạo một yêu cầu trong Apidog, thêm tiêu đề Authorization: Bearer của bạn, đưa phần thân JSON với ID mô hình của bạn vào và gửi đi. Bạn sẽ thấy token ek_ và thời hạn của nó ngay lập tức, vì vậy bạn biết rằng khóa và quyền truy cập tài khoản của mình hoạt động tốt ngay cả trước khi WebRTC được đưa vào. Đây là cùng một cách tiếp cận mà bạn sẽ sử dụng để kiểm tra nhanh bất kỳ bề mặt REST nào của OpenAI, như Responses API.
  2. Luồng tin nhắn WebSocket. Apidog có một client WebSocket, vì vậy bạn có thể mở kết nối đến wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini, thêm tiêu đề xác thực và gửi thủ công các tin nhắn session.update, conversation.item.create, và response.create từng cái một. Việc theo dõi các sự kiện máy chủ trở lại trong một bảng điều khiển dễ đọc sẽ làm cho trình tự sự kiện trở nên rõ ràng, và bạn có thể lưu các tin nhắn làm ví dụ cho nhóm của mình. Nếu bạn đã dựa vào các chiến lược kiểm thử API vững chắc, thì điều này hoàn toàn phù hợp.

Việc kiểm tra lớp truyền tải riêng lẻ có nghĩa là khi có gì đó hỏng trong ứng dụng, bạn đã biết rằng đó không phải là hợp đồng API. Tải Apidog nếu bạn muốn làm theo.

Kiểm soát chi phí

Đầu ra âm thanh là phần tốn kém, vì vậy một vài thói quen sau sẽ có ích:

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

FAQ

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

Bây giờ bạn đã có toàn bộ vòng lặp: ID mô hình chính xác, một nguyên mẫu WebSocket, một client WebRTC trên trình duyệt, cấu hình phiên, các công cụ và một cách để kiểm tra từng phần trong Apidog trước khi đưa vào sản xuất. Bắt đầu với ví dụ WebSocket chỉ có văn bản để xác nhận quyền truy cập, chuyển output_modalities sang âm thanh, sau đó chuyển sang WebRTC khi bạn đã sẵn sàng sử dụng micrô thực. Ghim một bản chụp, hướng dẫn mô hình nói ngắn gọn, và bạn sẽ có một tác nhân giọng nói độ trễ thấp mà không làm bạn bất ngờ về hóa đơn.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống