Sota Voice
Tài liệu

Giới hạn tốc độ

Giới hạn request mỗi giây theo khóa, giới hạn đồng thời theo tài khoản, và các header x-ratelimit-*.

Xem dạng Markdown

Request mỗi giây, theo khóa API

Mỗi khóa API được gửi một số request mỗi giây (mặc định của deployment: 20). Mọi route cần khóa API (speech, WebSocket, job, giọng, credit, token) đều được đếm, và response của chúng có header:

HeaderÝ nghĩaVí dụ
x-ratelimit-limit-requestsSố request mỗi giây được phép cho khóa20
x-ratelimit-remaining-requestsSố request còn lại trong cửa sổ một giây hiện tại19
x-ratelimit-reset-requestsThời gian tới khi cửa sổ đặt lại1s

Vượt giới hạn: 429 với code: rate_limited và header Retry-After: 1. Response lỗi này vẫn kèm các header x-ratelimit-*. Nếu bộ đếm tạm thời không khả dụng, request vẫn được phục vụ và các header này có thể vắng mặt.

curl -sD - -o /dev/null https://voice-be.sotalabs.io/v1/credits \
  -H "Authorization: Bearer $SOTA_API_KEY" | grep -i '^x-ratelimit'
x-ratelimit-limit-requests: 20
x-ratelimit-remaining-requests: 19
x-ratelimit-reset-requests: 1s

Request realtime đồng thời, theo tài khoản

Riêng với POST /v1/audio/speech và phiên WebSocket, mỗi tài khoản chỉ chạy được một số lượng nhất định cùng lúc (mặc định của deployment: 4). Vượt quá thì nhận 429 rate_limited ngay lập tức; request không bao giờ được xếp hàng. Với WebSocket, lỗi này trả về trước khi upgrade.

Job bất đồng bộ không tính vào giới hạn đồng thời này, nên văn bản dài hãy dùng job.

Thử lại đúng cách

  • Với 429, chờ đúng Retry-After giây (hiện là 1) rồi thử lại; thêm một chút ngẫu nhiên (jitter) nếu có nhiều worker.
  • Theo dõi x-ratelimit-remaining-requests để tự giãn nhịp trước khi chạm giới hạn.
  • Giới hạn tính theo khóa: chia tải ra nhiều khóa không làm tăng giới hạn đồng thời của tài khoản.
  • Cần giới hạn cao hơn? Liên hệ hỗ trợ.

Token trình duyệt (tok_...) tính vào giới hạn của khóa API đã tạo ra nó.