Quản Lý API Keys

API Key là phương thức xác thực duy nhất khi gọi tới AusyncLab API. Mỗi tài khoản có một Master Key mặc định và có thể tạo thêm các Sub Key khi đang sử dụng gói Pro năm hoặc Scale năm (tối đa 40 key mỗi tài khoản).

Khái niệm

Master Key: khóa gốc, được tạo tự động cho mọi tài khoản. Có thể thay đổi (rotate) nhưng không thể xóa. Chỉ có Master Key mới được phép gọi endpoint tạo key mới qua public API.
Sub Key: các khóa con do bạn tạo. Mỗi sub key có một name do bạn đặt — thường dùng để gắn key với một người dùng cuối hoặc một tenant trong hệ thống của bạn (ví dụ user-12345, tenant-acme). Sub key dùng được cho tất cả endpoint TTS, Voice Changer, Lipsync... giống như Master Key. Có thể xóa bất kỳ lúc nào.
Eligibility: tài khoản phải đang ở gói Pro năm hoặc Scale năm mới có thể tạo thêm sub key.

Lấy / Quản Lý Trên Web

Truy cập API Key dashboard (opens in a new tab) để:

Xem toàn bộ Master Key + Sub Key.
Tạo sub key mới (chỉ khi tài khoản đủ điều kiện).
Xóa sub key không còn dùng.
Thay đổi Master Key (key cũ sẽ ngừng hoạt động ngay lập tức).

Xác Thực

Mọi request tới AusyncLab API đều cần header:

X-API-Key: ak_xxxxxxxxxxxxxxxxxxxx

Master Key và Sub Key đều dùng cùng một định dạng và đều được chấp nhận trên tất cả endpoint dịch vụ. Chỉ riêng endpoint tạo sub key dưới đây yêu cầu Master Key.

Tạo Sub Key Qua Public API

Endpoint dùng để tạo thêm sub key tự động (ví dụ provisioning từ hệ thống nội bộ của bạn).

Endpoint: POST /api/v1/api-keys Authentication: X-API-Key phải là Master Key. Sub key không được phép gọi endpoint này. Eligibility: tài khoản đang ở gói Pro năm hoặc Scale năm, và chưa đạt giới hạn 40 key.

Request Body:

name (bắt buộc, tối đa 100 ký tự): định danh cho key — khuyến nghị dùng user ID hoặc tenant ID trong hệ thống của bạn (ví dụ user-12345, tenant-acme) để dễ tra cứu và thu hồi khi cần. Hiển thị trên dashboard.

CURL:

curl -X 'POST' \
  'https://api.ausynclab.io/api/v1/api-keys' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_master_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "tenant-acme"
  }'

Phản hồi:

201 Created

{
  "status": 201,
  "result": {
    "id": "8f1c2b9a-1234-4abc-9def-1234567890ab",
    "customer_id": "1a2b3c4d-5678-90ab-cdef-1234567890ab",
    "api_key": "ak_NewlyCreatedKeyValue.signature",
    "name": "tenant-acme",
    "is_master": false,
    "created_at": "2026-05-12T08:00:00Z",
    "last_used_at": null
  },
  "message": "API key created."
}

Lưu ý: api_key chỉ trả về một lần duy nhất ngay sau khi tạo. Hãy lưu trữ ngay vào nơi an toàn (vault, secret manager...). Nếu bị mất, bạn cần xóa key và tạo lại.

Mã Lỗi

HTTP	Code	Ý nghĩa
401	`invalid_api_key`	`X-API-Key` không hợp lệ hoặc đã bị thay đổi.
403	`api_key_not_master`	Bạn đang dùng một sub key — chỉ Master Key mới được tạo key mới.
403	`api_key_plan_not_eligible`	Tài khoản không ở gói Pro năm / Scale năm.
409	`api_key_limit_reached`	Đã đạt 40 key. Hãy xóa bớt trước khi tạo thêm.

Ví dụ response lỗi:

{
  "detail": "Adding API keys requires an active Pro year or Scale year subscription."
}

Best Practices

Một key cho mỗi user / tenant: mint riêng một sub key cho mỗi người dùng cuối hoặc tenant trong hệ thống của bạn. Khi user rời đi hoặc tenant hủy hợp đồng, chỉ cần xóa đúng key đó — không ảnh hưởng những user còn lại.
Đặt name trùng với ID nội bộ: dùng user-{id} hoặc tenant-{id} để khi cần tra cứu trên dashboard có thể đối chiếu trực tiếp với hệ thống của bạn.
Không commit key vào source code: lưu trong vault / secret manager của từng tenant, không trộn lẫn.
Thay đổi Master Key định kỳ: nếu nghi ngờ Master Key bị lộ, dùng nút "Thay Đổi Master Key" trên dashboard. Lưu ý: sau khi thay đổi, key cũ ngừng hoạt động ngay (các sub key vẫn dùng được bình thường).

Instant Avatar Rate Limit