Xác thực
Khóa API cho server, token ngắn hạn cho trình duyệt.
Khóa API
Request tới /v1 gửi khóa bí mật trong header Authorization (GET /v1/models là ngoại lệ, không cần khóa):
curl https://voice-be.sotalabs.io/v1/credits \
-H "Authorization: Bearer $SOTA_API_KEY"- Khóa có dạng
sk_live_..., tạo và thu hồi trong dashboard (Khóa API). - Khóa đầy đủ chỉ hiện một lần khi tạo; sau đó chỉ còn prefix. Mất khóa thì tạo khóa mới và thu hồi khóa cũ.
- Thiếu, sai hoặc đã thu hồi khóa:
401 unauthorized. Tài khoản bị tạm khóa:403 account_suspended. - Giới hạn tốc độ tính theo từng khóa, xem Giới hạn tốc độ.
Khóa API là bí mật của server. Đừng nhúng vào ứng dụng web, app di động hay repo công khai.
Token cho trình duyệt
Trình duyệt không đặt được header khi mở WebSocket và không được giữ khóa API. Thay vào đó:
- Server của bạn gọi
POST /v1/tokensbằng khóa API. - Server trả
token(tok_...) cho trang web. - Trang mở WebSocket với
?token=tok_....
curl -X POST https://voice-be.sotalabs.io/v1/tokens \
-H "Authorization: Bearer $SOTA_API_KEY"{"object":"token","token":"tok_3q2r8mYwK1x0b7sN","expires_at":1763366700}Quy tắc của token:
- Sống 5 phút (300 giây) kể từ lúc tạo, xem
expires_at. Hãy mở kết nối trước khi hết hạn; kết nối đã mở không bị cắt khi token hết hạn. - Chỉ dùng được với
GET /v1/audio/speech/stream(tham sốtoken), không dùng cho route HTTP khác. - Gắn với tài khoản của khóa đã tạo ra nó; credit trừ vào tài khoản đó.
- Origin của trang phải nằm trong danh sách cho phép của deployment.
- Tạo token theo yêu cầu (mỗi lần mở kết nối), đừng lưu lâu. Không ghi token vào log.
- Thu hồi khóa API không thu hồi các token đã cấp từ khóa đó: chúng vẫn hợp lệ đến hết TTL (300 giây).
Ví dụ endpoint trên server (Node.js, Express) cấp token cho trang đã đăng nhập:
app.post('/sota-token', requireUser, async (_req, res) => {
const r = await fetch('https://voice-be.sotalabs.io/v1/tokens', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.SOTA_API_KEY}` },
});
if (!r.ok) return res.status(502).end();
const { token, expires_at } = await r.json();
res.set('Cache-Control', 'no-store').json({ token, expires_at });
});Phía trình duyệt xem Voice agent qua WebSocket.