Hướng dẫn media
Âm thanh và thời gian thực
Tạo giọng nói, chuyển đổi âm thanh thành văn bản, dịch thuật giọng nói hoặc mở phiên làm việc thời gian thực
Sử dụng các endpoint âm thanh khi kết quả trả về là tệp hoặc văn bản. Sử dụng endpoint WebSocket thời gian thực để có trải nghiệm âm thanh hai chiều trực tiếp.
Chọn một endpoint
| Nhu cầu | Endpoint | Sử dụng khi |
|---|---|---|
| Chuyển văn bản thành giọng nói | POST /v1/audio/speech | Bạn cần một tệp âm thanh từ văn bản. |
| Chuyển đổi âm thanh thành văn bản | POST /v1/audio/transcriptions | Bạn cần văn bản từ một tệp âm thanh. |
| Dịch thuật âm thanh | POST /v1/audio/translations | Bạn cần văn bản đã dịch từ một tệp âm thanh. |
| WebSocket thời gian thực | WS /v1/realtime?model={model} | Bạn cần truyền phát âm thanh hai chiều qua WebSocket. GET /v1/realtime thuần túy chỉ trả về siêu dữ liệu. |
Chọn một model
Hãy đọc danh sách model hiện tại thay vì mã hóa cứng (hard-coding) chúng. Kiểm tra chi tiết của model đã chọn để đảm bảo hỗ trợ thời gian thực trước khi mở socket.
curl "https://api.tokenlab.sh/v1/models?recommended_for=tts" \
-H "Authorization: Bearer sk-your-api-key"
curl "https://api.tokenlab.sh/v1/models?recommended_for=stt" \
-H "Authorization: Bearer sk-your-api-key"Các yêu cầu về âm thanh
Speech trả về âm thanh trong phản hồi HTTP. Transcription và translation có thể trả về văn bản cuối cùng hoặc một tác vụ đã được chấp nhận. Khi phần thân phản hồi chứa ID tác vụ và trạng thái thay vì văn bản cuối cùng, hãy lưu ID đó và thực hiện poll GET /v1/tasks/{id} cho đến khi hoàn tất hoặc thất bại. Hãy dành đủ thời gian cho các tệp lớn và giữ lại Request ID.
Các URL kết quả âm thanh là các URL phương tiện của TokenLab có hiệu lực trong 30 ngày. media_retention.items báo cáo trạng thái lưu của từng mục và expires_at; phản hồi có thể bỏ qua media_retention khi trạng thái lưu không được xác định kịp thời, và URL vẫn hoạt động. Các phản hồi âm thanh dạng nhúng hoặc nhị phân nằm ngoài phạm vi lưu giữ URL này. Xem Lưu giữ dữ liệu.
curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-tts",
"voice": "eve",
"input": "Welcome to TokenLab."
}' \
--output speech.mp3Các phiên làm việc thời gian thực
Mở một WebSocket với model trong chuỗi truy vấn (query string) và khóa API trong tiêu đề Authorization. Giữ đúng định dạng sự kiện được ghi lại cho model thời gian thực đã chọn và đóng socket khi phiên làm việc kết thúc.
Một phiên làm việc kéo dài tối đa 1 giờ. Sau đó, máy chủ sẽ đóng socket với mã 1000 và lý do session_timeout. Một tin nhắn đơn lẻ có thể lên tới 32 MiB; tin nhắn lớn hơn sẽ khiến socket đóng với mã 1009. Một số model thời gian thực, chẳng hạn như grok-voice-think-fast-2.0, chỉ chấp nhận các khung âm thanh và cập nhật phiên làm việc. Một mục nhập văn bản sẽ trả về lỗi unsupported_realtime_text_input và đóng socket với mã 1008.
Hướng dẫn này chỉ bao gồm tập hợp con WebSocket. TokenLab hiện không cung cấp OpenAI Realtime REST client secret, translation client secret, Calls, hoặc các endpoint quản lý phiên làm việc beta cũ.
Đối với ví dụ phía máy chủ bên dưới, hãy cài đặt ws và đặt TOKENLAB_REALTIME_MODEL thành một model hiện tại có chi tiết khai báo /v1/realtime. Cung cấp TOKENLAB_API_KEY trong môi trường máy chủ; chỉ riêng tên biến không thiết lập hỗ trợ thời gian thực.
npm install wsimport WebSocket from 'ws';
const model = process.env.TOKENLAB_REALTIME_MODEL;
const apiKey = process.env.TOKENLAB_API_KEY;
if (!model || !apiKey) throw new Error('Set TOKENLAB_REALTIME_MODEL and TOKENLAB_API_KEY');
const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', model);
const socket = new WebSocket(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
socket.on('message', (event) => console.log(event.toString()));
socket.on('error', (error) => console.error(error.message));
process.once('SIGINT', () => socket.close(1000, 'Client stopped'));Hiển thị tiến trình một cách an toàn
- Lưu các tệp âm thanh đã tạo thay vì phát lại cùng một yêu cầu khi làm mới trang.
- Đối với transcription và translation, hãy hiển thị trạng thái tải lên và xử lý ngay cả khi lệnh gọi API là đồng bộ.
- Đối với thời gian thực, hãy xử lý các sự kiện đóng kết nối và chỉ kết nối lại sau khi người dùng bắt đầu một phiên làm việc mới.
- Không đưa khóa API, URL riêng tư hoặc bí mật tài khoản vào phần nhập văn bản âm thanh.
Tài liệu tham khảo API
| Chủ đề | Tham khảo |
|---|---|
| Tạo giọng nói | Tạo giọng nói |
| Tạo bản ghi âm | Tạo bản ghi âm (Transcription) |
| Tạo bản dịch | Tạo bản dịch |
| WebSocket thời gian thực | Realtime WebSocket |
| Danh sách model | Liệt kê các Model |
| Thanh toán & Giá cả | Billing & Pricing |