Sota Voice
Tài liệu

Xác thực

Khóa API cho server, token ngắn hạn cho trình duyệt.

Xem dạng Markdown

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 đó:

  1. Server của bạn gọi POST /v1/tokens bằng khóa API.
  2. Server trả token (tok_...) cho trang web.
  3. 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.