Khóa API

Phương thức, trường yêu cầu và phản hồi.

Hướng dẫn đầy đủ

Phần này có 5 phương thức. Mở phương thức để xem điều kiện truy cập, trường yêu cầu và phản hồi.

Phương thức và đường dẫn	Mô tả	Quyền truy cập
`GET /api/v1/keys`	Danh sách — khóa API	Token trang quản lý tài khoản
`POST /api/v1/keys`	Tạo khóa API	Token trang quản lý tài khoản
`DELETE /api/v1/keys/:id`	Xóa — khóa API	Token trang quản lý tài khoản
`GET /api/v1/keys/:id`	Lấy theo mã định danh — khóa API	Token trang quản lý tài khoản
`PUT /api/v1/keys/:id`	Thay đổi khóa API	Token trang quản lý tài khoản

GET /api/v1/keys — Danh sách — khóa API

Quyền truy cập: Token trang quản lý tài khoản

GET/api/v1/keys

Đọc; lấy ID từ phản hồi trước đó của bạn

curl --fail-with-body "https://ailoot.ai/api/v1/keys" \
  -H "Authorization: Bearer $TOKEN"

Tham số truy vấn

Trường	Kiểu	Bắt buộc	Kiểm tra / mô tả
`sort_by`	`string`	không	; mặc định: created_at
`sort_order`	`string`	không	; mặc định: desc
`search`	`string`	không
`status`	`string`	không
`page`	`integer`	không	; mặc định: 1; positive; page_size/limit <=1000
`page_size`	`integer`	không	; mặc định: 20; positive; page_size/limit <=1000
`limit`	`integer`	không	; mặc định: 20; positive; page_size/limit <=1000

Không cần nội dung yêu cầu. Gửi các tham số nêu trên trong URL.

Phản hồi

Phản hồi JSON chứa code, message và data. Nội dung data được mô tả trong các lược đồ bên dưới.

Lược đồ dữ liệu phản hồi: APIKey. Các trường và kiểu dữ liệu nằm trên trang “Lược đồ dữ liệu”.

Lược đồ phản hồi, các giá trị chỉ để minh họa

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "user_id": "PLACEHOLDER_USER_ID (integer)",
        "key": "PLACEHOLDER_KEY (string)",
        "name": "PLACEHOLDER_NAME (string)",
        "status": "PLACEHOLDER_STATUS (string)",
        "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
        "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
        "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
        "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
        "quota": "PLACEHOLDER_QUOTA (number)",
        "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
        "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
        "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
        "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
        "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
        "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
        "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
        "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
        "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
        "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
        "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
        "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
        "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
        "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
        "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
        "user": "PLACEHOLDER_USER (object)"
      }
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}

Đặc điểm: Mọi dữ liệu cá nhân và đối tượng đều được giới hạn theo chủ thể JWT.

Đặc điểm: Phản hồi chứa key bí mật; không công khai giá trị thật.

POST /api/v1/keys — Tạo khóa API

Quyền truy cập: Token trang quản lý tài khoản

POST/api/v1/keys

Các trường JSON / biểu mẫu

Trường	Kiểu	Bắt buộc	Kiểm tra / mô tả
`name`	`string`	có	required
`custom_key`	`string`	không	; Giá trị khóa tự chọn, không bắt buộc; có thể là null
`ip_whitelist`	`array`	không	; Danh sách IP được phép
`ip_blacklist`	`array`	không	; Danh sách IP bị chặn
`quota`	`number`	không	; Giới hạn chi tiêu của khóa bằng USD; có thể là null
`expires_in_days`	`integer`	không	; Thời hạn hiệu lực tính bằng ngày; có thể là null
`rate_limit_5h`	`number`	không	; có thể là null
`rate_limit_1d`	`number`	không	; có thể là null
`rate_limit_7d`	`number`	không	; có thể là null

Mẫu nội dung yêu cầu

{
  "name": "PLACEHOLDER_NAME (string)",
  "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)"
}

PLACEHOLDER biểu thị dữ liệu bạn nhập và kiểu dữ liệu đó. Thay các giá trị và chỉ giữ những trường tùy chọn cần thiết; không gửi chuỗi đánh dấu thay cho số, boolean, đối tượng hoặc mảng.

Lược đồ yêu cầu: CreateAPIKeyRequest

Phản hồi

Phản hồi JSON chứa code, message và data. Nội dung data được mô tả trong các lược đồ bên dưới.

Lược đồ dữ liệu phản hồi: APIKey. Các trường và kiểu dữ liệu nằm trên trang “Lược đồ dữ liệu”.

Lược đồ phản hồi, các giá trị chỉ để minh họa

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Đặc điểm: Mọi dữ liệu cá nhân và đối tượng đều được giới hạn theo chủ thể JWT.

Đặc điểm: Thao tác thay đổi trạng thái hoặc tiếp tục quy trình ủy quyền dùng một lần; ví dụ mô tả hợp đồng và không được thực thi.

Đặc điểm: Hỗ trợ Idempotency-Key; gửi lại sẽ trả phản hồi đã lưu kèm X-Idempotency-Replayed.

Đặc điểm: Phản hồi chứa key bí mật; không công khai giá trị thật.

DELETE /api/v1/keys/:id — Xóa — khóa API

Quyền truy cập: Token trang quản lý tài khoản

DELETE/api/v1/keys/:id

Tham số đường dẫn

Trường	Kiểu	Bắt buộc	Kiểm tra / mô tả
`id`	`integer`	có

Không cần nội dung yêu cầu.

Phản hồi

Phản hồi JSON chứa code, message và data. Nội dung data được mô tả trong các lược đồ bên dưới.

Lược đồ phản hồi, các giá trị chỉ để minh họa

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "VALUE_FROM_RESPONSE"
  }
}

Đặc điểm: Mọi dữ liệu cá nhân và đối tượng đều được giới hạn theo chủ thể JWT.

Đặc điểm: Thao tác thay đổi trạng thái hoặc tiếp tục quy trình ủy quyền dùng một lần; ví dụ mô tả hợp đồng và không được thực thi.

Đặc điểm: Phản hồi chứa key bí mật; không công khai giá trị thật.

GET /api/v1/keys/:id — Lấy theo mã định danh — khóa API

Quyền truy cập: Token trang quản lý tài khoản

GET/api/v1/keys/:id

Đọc; lấy ID từ phản hồi trước đó của bạn

curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \
  -H "Authorization: Bearer $TOKEN"

Tham số đường dẫn

Trường	Kiểu	Bắt buộc	Kiểm tra / mô tả
`id`	`integer`	có

Không cần nội dung yêu cầu. Gửi các tham số nêu trên trong URL.

Phản hồi

Phản hồi JSON chứa code, message và data. Nội dung data được mô tả trong các lược đồ bên dưới.

Lược đồ dữ liệu phản hồi: APIKey. Các trường và kiểu dữ liệu nằm trên trang “Lược đồ dữ liệu”.

Lược đồ phản hồi, các giá trị chỉ để minh họa

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Đặc điểm: Mọi dữ liệu cá nhân và đối tượng đều được giới hạn theo chủ thể JWT.

Đặc điểm: Phản hồi chứa key bí mật; không công khai giá trị thật.

PUT /api/v1/keys/:id — Thay đổi khóa API

Quyền truy cập: Token trang quản lý tài khoản

PUT/api/v1/keys/:id

Tham số đường dẫn

Trường	Kiểu	Bắt buộc	Kiểm tra / mô tả
`id`	`integer`	có

Các trường JSON / biểu mẫu

Trường	Kiểu	Bắt buộc	Kiểm tra / mô tả
`name`	`string`	không
`status`	`string`	không	omitempty,oneof=active inactive
`ip_whitelist`	`array`	không	; IP được phép: null không thay đổi danh sách, mảng rỗng xóa toàn bộ danh sách; có thể là null
`ip_blacklist`	`array`	không	; IP bị chặn: null không thay đổi danh sách, mảng rỗng xóa toàn bộ danh sách; có thể là null
`quota`	`number`	không	; Giới hạn chi tiêu của khóa bằng USD; 0 — không giới hạn; có thể là null
`expires_at`	`string`	không	; Thời điểm hết hiệu lực theo định dạng ISO 8601; có thể là null
`reset_quota`	`boolean`	không	; Đặt lại phần giới hạn chi tiêu đã sử dụng; có thể là null
`rate_limit_5h`	`number`	không	; có thể là null
`rate_limit_1d`	`number`	không	; có thể là null
`rate_limit_7d`	`number`	không	; có thể là null
`reset_rate_limit_usage`	`boolean`	không	; Đặt lại mức sử dụng của các giới hạn theo khoảng thời gian; có thể là null

Mẫu nội dung yêu cầu

{
  "name": "PLACEHOLDER_NAME (string)",
  "status": "PLACEHOLDER_STATUS (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
  "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
  "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)"
}

Lược đồ yêu cầu: UpdateAPIKeyRequest

Phản hồi

Phản hồi JSON chứa code, message và data. Nội dung data được mô tả trong các lược đồ bên dưới.

Lược đồ dữ liệu phản hồi: APIKey. Các trường và kiểu dữ liệu nằm trên trang “Lược đồ dữ liệu”.

Lược đồ phản hồi, các giá trị chỉ để minh họa

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Đặc điểm: Mọi dữ liệu cá nhân và đối tượng đều được giới hạn theo chủ thể JWT.

Đặc điểm: Thao tác thay đổi trạng thái hoặc tiếp tục quy trình ủy quyền dùng một lần; ví dụ mô tả hợp đồng và không được thực thi.

Đặc điểm: Phản hồi chứa key bí mật; không công khai giá trị thật.

Đặc điểm: Khi khóa còn các yêu cầu chưa hoàn thành có khoản giữ trước, không thể giảm hoặc đặt lại giới hạn chi tiêu của khóa. Chỉ gửi những trường bạn thay đổi.

Còn câu hỏi? Hãy gửi Request ID và mô tả — chúng tôi sẽ giúp tìm hiểu.Liên hệ hỗ trợ