API Dịch Thời Gian Thực
Thêm tính năng dịch giọng nói sang giọng nói trực tiếp vào bất kỳ ứng dụng nào chỉ trong vài phút. Truyền âm thanh vào và nhận lại âm thanh cùng bản ghi đã được dịch — tất cả thông qua một kết nối WebSocket duy nhất.
Tại sao chọn API Dịch Thời Gian Thực?
Được xây dựng cho các ứng dụng cần dịch tức thì và liên tục. Một kết nối duy nhất và ổn định sẽ xử lý toàn bộ phiên — không polling, không độ trễ, không phức tạp.
Độ Trễ Siêu Thấp
Âm thanh streaming được dịch và trả về theo thời gian thực. Không cần các vòng request-response — kết quả đến ngay khi người nói đang nói.
Âm Thanh Vào, Âm Thanh Ra
Gửi âm thanh thô từ micro và nhận lại giọng nói đã được dịch. Cả transcript đầu vào và đầu ra cũng được stream để bạn có thể hiển thị phụ đề trực tiếp.
Hơn 130 Ngôn Ngữ
Dịch sang bất kỳ ngôn ngữ phổ biến nào bằng mã ngôn ngữ chuẩn BCP-47. Thay đổi ngôn ngữ đích giữa các phiên mà không cần chỉnh sửa SDK.
Bảo Mật Theo Mặc Định
Mỗi kết nối đều được xác thực bằng JWT token của bạn. Các phiên được tách biệt theo từng người dùng — âm thanh của bạn không bao giờ bị chia sẻ hoặc lưu trữ.
Kết Nối & Xác Thực
API Dịch Thời Gian Thực hoạt động trên một namespace Socket.IO chuyên dụng. Truyền khóa API của bạn dưới dạng query parameter khi tạo kết nối — máy chủ sẽ xác thực trước khi bất kỳ phiên nào bắt đầu.
wss://api.gpttranslator.co └── namespace: /api/realtime-translator
import { io } from 'socket.io-client'; // Connect to the Realtime Translation namespace const socket = io('https://api.gpttranslator.co/api/realtime-translator', { transports: ['websocket'], query: { apiKey: 'YOUR_API_KEY' // your GPT Translator API key }, });
Lưu ý: Lấy khóa API của bạn từ bảng điều khiển GPT Translator trong mục API Keys. Các kết nối không có khóa API hợp lệ sẽ bị từ chối ngay lập tức.
Không bao giờ để lộ khóa API trong mã phía client
Ví dụ mã ở trên chỉ mang tính minh họa. Việc nhúng trực tiếp khóa API vào JavaScript trên trình duyệt sẽ khiến bất kỳ ai kiểm tra mã nguồn trang hoặc lưu lượng mạng đều có thể nhìn thấy — và họ có thể sử dụng khóa của bạn để tiêu hao toàn bộ số token.
✅ Khuyến nghị: sử dụng proxy thông qua backend của riêng bạn
Máy chủ của bạn sẽ lưu trữ khóa API một cách an toàn và mở kết nối Socket.IO thay cho trình duyệt. Trình duyệt sẽ kết nối với máy chủ của bạn, không kết nối trực tiếp đến API dịch.
// Your backend holds the key — the browser never sees it
const socket = io('https://api.gpttranslator.co/api/realtime-translator', {
transports: ['websocket'],
query: { apiKey: process.env.GPT_TRANSLATOR_API_KEY },
});
// Proxy events between the browser client and the translation API
browserSocket.on('translation_start', (data) => socket.emit('translation_start', data));
browserSocket.on('audio_chunk', (chunk) => socket.emit('audio_chunk', chunk));
browserSocket.on('translation_stop', () => socket.emit('translation_stop'));
socket.on('output_audio', (data) => browserSocket.emit('output_audio', data));
socket.on('output_transcript', (data) => browserSocket.emit('output_transcript', data));
socket.on('input_transcript', (data) => browserSocket.emit('input_transcript', data));Vòng Đời Phiên
Mỗi phiên dịch đều tuân theo một chuỗi năm bước đơn giản. Hiểu rõ thứ tự này sẽ giúp bạn xây dựng một tích hợp ổn định.
Bắt đầu phiên
bạn gửiEmit translation_start với mã ngôn ngữ đích. Máy chủ sẽ giữ trước số token của bạn và bắt đầu khởi tạo phiên.
Chờ tín hiệu sẵn sàng
bạn lắng ngheMáy chủ sẽ emit ba sự kiện trạng thái theo thứ tự: session_initializing, translation_ready và cuối cùng là ready_for_audio. Chỉ bắt đầu gửi âm thanh sau khi nhận được ready_for_audio.
Stream các đoạn âm thanh
bạn gửiLiên tục emit các sự kiện audio_chunk với âm thanh PCM16 được mã hóa base64 từ micro. Giữ các đoạn nhỏ (khoảng 100 ms mỗi đoạn) để đạt độ trễ thấp nhất.
Nhận kết quả đã dịch
bạn lắng ngheTrong khi dịch, máy chủ sẽ stream output_audio (giọng nói đã dịch), output_transcript (văn bản đã dịch) và input_transcript (văn bản gốc được nhận diện) — tất cả dưới dạng các delta tăng dần.
Kết thúc phiên
bạn gửiEmit translation_stop để đóng phiên một cách an toàn. Việc sử dụng token sẽ được hoàn tất và sự kiện translation_closed xác nhận phiên đã kết thúc.
Tài Liệu Sự Kiện
Tài liệu đầy đủ về mọi sự kiện trong API Dịch Thời Gian Thực — những gì bạn gửi và những gì bạn nhận.
Các Sự Kiện Bạn Gửi
bạn gửitranslation_startBắt đầu một phiên dịch mới. Truyền mã ngôn ngữ BCP-47 cho ngôn ngữ đích.
{
"targetLanguage": "es" // BCP-47 language code (e.g. "fr", "de", "zh", "ja")
}audio_chunkGửi một đoạn âm thanh thô từ micro. Trường audioData phải là buffer âm thanh PCM16 mono được mã hóa base64 với tần số lấy mẫu 24.000 Hz.
{
"audioData": "<base64-encoded PCM16 mono audio>"
// Sample rate: 24 000 Hz
// Encoding: 16-bit PCM, little-endian
// Send continuously while the user speaks
}translation_stopKết thúc phiên một cách an toàn. Máy chủ hoàn tất việc tính phí và emit translation_closed.
Các Sự Kiện Bạn Lắng Nghe
bạn lắng nghesession_initializingstatusĐược emit ngay sau translation_start. Cho biết phiên đang được thiết lập — chưa sẵn sàng cho âm thanh.
translation_readystatusĐược emit khi kết nối phía máy chủ đã được thiết lập. Vẫn đang chờ kích hoạt phiên cuối cùng.
ready_for_audiostatusPhiên đã hoạt động hoàn toàn. Bắt đầu stream các sự kiện audio_chunk ngay bây giờ.
output_audiostreamMột đoạn âm thanh giọng nói đã dịch. Delta là một buffer âm thanh PCM16 được mã hóa base64. Hãy buffer các delta liên tiếp và phát chúng theo đúng thứ tự.
{
"delta": "<base64-encoded PCM16 audio chunk>"
// Decoded and played directly to the output speaker
// Arrives incrementally — buffer chunks for smooth playback
}output_transcriptstreamMột phần của văn bản đã dịch. Ghép các delta lại với nhau để xây dựng transcript đầy đủ trong giao diện của bạn.
{
"delta": "Hola, ¿cómo estás?" // translated text fragment
}input_transcriptstreamMột phần của giọng nói gốc đã được nhận diện. Ghép các delta lại với nhau để xây dựng phụ đề ngôn ngữ nguồn.
{
"delta": "Hello, how are you?" // recognized source speech fragment
}translation_closedstatusXác nhận rằng phiên đã kết thúc thành công — sau translation_stop hoặc khi máy chủ đóng phiên do hết token.
translation_errorerrorĐã xảy ra lỗi không mong muốn. Trường message sẽ giải thích điều gì đã xảy ra. Phiên có thể vẫn còn hoạt động — bạn có thể thử lại hoặc gọi translation_stop.
{
"message": "Translation session error. Please try again."
}insufficient_tokenserrorSố dư token của bạn đã hết. Phiên sẽ tự động đóng. Nâng cấp gói của bạn để tiếp tục.
{
"message": "You have reached the limit of words for translation...",
"remainingTokens": 0
}Ví Dụ Tích Hợp Hoàn Chỉnh
Một ví dụ JavaScript tối giản nhưng đầy đủ cho thấy cách kết nối, bắt đầu phiên, stream âm thanh, xử lý tất cả sự kiện từ máy chủ và kết thúc phiên đúng cách.
import { io } from 'socket.io-client';
const socket = io('https://api.gpttranslator.co/api/realtime-translator', {
transports: ['websocket'],
query: { apiKey: 'YOUR_API_KEY' },
});
// ─── Listen for server events ───────────────────────────────────────
socket.on('session_initializing', () => {
console.log('Session is being prepared...');
});
socket.on('translation_ready', () => {
console.log('Session connected. Waiting for activation...');
});
socket.on('ready_for_audio', () => {
console.log('Ready! Start streaming audio chunks now.');
startMicrophone(); // begin capturing and sending audio
});
socket.on('output_audio', ({ delta }) => {
// delta is a base64-encoded PCM16 audio chunk
playAudioChunk(atob(delta));
});
socket.on('output_transcript', ({ delta }) => {
// Append translated text delta to your UI
appendToTranscript('translated', delta);
});
socket.on('input_transcript', ({ delta }) => {
// Append recognized source speech to your UI
appendToTranscript('original', delta);
});
socket.on('translation_closed', () => {
console.log('Session ended.');
stopMicrophone();
});
socket.on('translation_error', ({ message }) => {
console.error('Error:', message);
stopMicrophone();
});
socket.on('insufficient_tokens', ({ message, remainingTokens }) => {
console.warn('Out of tokens:', message, 'remaining:', remainingTokens);
stopMicrophone();
showUpgradePrompt();
});
// ─── Start a session ────────────────────────────────────────────────
socket.emit('translation_start', { targetLanguage: 'es' });
// ─── Stream audio chunks ────────────────────────────────────────────
function onAudioData(pcm16Base64) {
socket.emit('audio_chunk', { audioData: pcm16Base64 });
}
// ─── Stop the session ───────────────────────────────────────────────
function stopSession() {
socket.emit('translation_stop');
}Cách Hoạt Động Của Thanh Toán
Dịch thời gian thực được tính phí dựa trên thời lượng phiên — khoảng thời gian từ khi phiên được kích hoạt cho đến translation_stop hoặc hết token. Không tính theo ký tự hay từ.
Thanh Toán Theo Giây
Mức sử dụng được đo bằng giây từ lúc phiên hoạt động hoàn toàn cho đến khi kết thúc. Các giây lẻ sẽ được làm tròn lên.
Token Bị Trừ Theo Thời Gian Thực
Token sẽ bị trừ khỏi số dư của bạn vào cuối mỗi phiên dựa trên thời lượng thực tế. Số dư khả dụng của bạn sẽ được kiểm tra trước khi phiên bắt đầu.
Giới Hạn Tự Động
Phiên sẽ tự động kết thúc khi số token còn lại của bạn sắp hết. Bạn sẽ nhận được sự kiện insufficient_tokens trước khi phiên đóng.
Ước Tính Mức Tiêu Thụ Token
Lưu ý: Ước tính token chỉ mang tính tương đối. Mức tiêu thụ thực tế phụ thuộc vào độ nhiễu âm thanh và hoạt động của phiên. Kiểm tra dashboard để xem mức sử dụng theo thời gian thực.
Yêu Cầu Định Dạng Âm Thanh
API yêu cầu một định dạng âm thanh cụ thể để đạt độ chính xác cao nhất và độ trễ thấp nhất. Sử dụng đoạn mã dưới đây để thu và chuyển đổi âm thanh micro trên trình duyệt.
PCM 16-bit, little-endian24 000 Hz1 (mono)Base64 string// Capture PCM16 audio from the browser microphone
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const audioContext = new AudioContext({ sampleRate: 24000 });
const source = audioContext.createMediaStreamSource(stream);
const processor = audioContext.createScriptProcessor(4096, 1, 1);
processor.onaudioprocess = (e) => {
const float32 = e.inputBuffer.getChannelData(0);
// Convert Float32 → Int16 PCM
const int16 = new Int16Array(float32.length);
for (let i = 0; i < float32.length; i++) {
int16[i] = Math.max(-32768, Math.min(32767, float32[i] * 32768));
}
// Base64-encode and send
const base64 = btoa(String.fromCharCode(...new Uint8Array(int16.buffer)));
socket.emit('audio_chunk', { audioData: base64 });
};
source.connect(processor);
processor.connect(audioContext.destination);Câu Hỏi Thường Gặp
Các câu hỏi phổ biến về tích hợp và sử dụng API Dịch Thời Gian Thực.