API quản lý

Tổng quan

Management API cho phép bạn quản lý API key của tổ chức và truy xuất mức sử dụng cũng như chi phí theo từng key mà không cần dùng inference API key thông thường. Bạn có thể phát hành và xoay vòng management token từ trang Settings trong Dashboard.

Authorization: Bearer mt-your-management-token

Management token khác với inference API key. Hãy dùng mt-... cho /v1/management/*, và dùng sk-... cho các endpoint suy luận như /v1/responses.

Endpoint khả dụng

Endpoint	Method	Mô tả
`/v1/management/api-keys`	GET	Liệt kê API key người dùng trong tổ chức hiện tại
`/v1/management/api-keys`	POST	Tạo API key người dùng mới
`/v1/management/api-keys/{keyId}`	PATCH	Cập nhật tên, giới hạn sử dụng, model cho phép, thời gian hết hạn hoặc trạng thái
`/v1/management/api-keys/{keyId}/usage`	GET	Lấy chi tiết usage có phân trang cho một key cụ thể
`/v1/management/api-keys/{keyId}/billing`	GET	Lấy breakdown chi phí tổng hợp cho một key cụ thể

Hợp đồng bộ lọc usage

GET /v1/management/api-keys/{keyId}/usage hỗ trợ các query parameter sau.

Tham số	Kiểu	Mặc định / giới hạn	Mô tả
`page`	integer	mặc định `1`, tối thiểu `1`	Số trang bắt đầu từ 1
`limit`	integer	mặc định `50`, tối thiểu `1`, tối đa `100`	Kích thước mỗi trang
`logicalModel`	string	độ dài tối đa `100`	Tên model logic được yêu cầu
`modelVendor`	string	độ dài tối đa `100`	Nhà cung cấp model công khai
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`
`accessChannel`	enum	-	`platform` hoặc `byok`
`startDate`	string	-	Cận dưới bao gồm; chấp nhận RFC3339 có múi giờ hoặc `YYYY-MM-DD`
`endDate`	string	-	Cận trên bao gồm; chấp nhận RFC3339 có múi giờ hoặc `YYYY-MM-DD`

Nếu truyền đồng thời startDate và endDate, thì startDate phải nhỏ hơn hoặc bằng endDate.

Hợp đồng body API key

POST /v1/management/api-keys

Trường	Kiểu	Mặc định / giới hạn	Mô tả
`name`	string	bắt buộc, mặc định `Default Key`, độ dài `1-50`	Tên hiển thị; server sẽ cắt khoảng trắng ở đầu và cuối
`limitAmount`	number \| null	tối thiểu `0`, tối đa `100000`	`null` hoặc bỏ qua = không giới hạn, `0` = quota bằng 0, số dương = trần chi tiêu USD
`limitCurrency`	enum	mặc định `USD`	Tùy chọn: `USD` hoặc `CNY`. Khi đặt là `CNY`, `limitAmount` sẽ được hiểu là RMB và được server quy đổi sang USD trước khi lưu
`models`	string[]	mặc định `[]`	Danh sách cho phép model logic tùy chọn
`expiresAt`	string \| null	datetime RFC3339	`null` nghĩa là không hết hạn

PATCH /v1/management/api-keys/

Trường	Kiểu	Mặc định / giới hạn	Mô tả
`status`	enum	-	`active`, `inactive`, `revoked`
`name`	string	độ dài `1-50`	Tên hiển thị sau khi cập nhật
`limitAmount`	number \| null	tối thiểu `0`, tối đa `100000`	`null` = không giới hạn, `0` = quota bằng 0
`limitCurrency`	enum	mặc định `USD`	Tùy chọn: `USD` hoặc `CNY`. Khi đặt là `CNY`, `limitAmount` sẽ được hiểu là RMB và được server quy đổi sang USD trước khi lưu
`models`	string[]	-	Danh sách model logic cho phép sau khi cập nhật
`expiresAt`	string \| null	datetime RFC3339	`null` sẽ xoá thời gian hết hạn

Yêu cầu PATCH phải có ít nhất một trường.

Hợp đồng tiền tệ

Mặc định, limitAmount ở phía request được hiểu là USD. Đặt limitCurrency: "CNY" để gửi hạn mức bằng RMB; server sẽ quy đổi sang USD theo tỷ giá hiện tại trước khi lưu.
Các trường tiền tệ trong response giữ nguyên giá trị USD gốc và bổ sung bản hiển thị RMB với hậu tố _cny.
exchange_rate được trả về cùng metadata của API key và là tỷ giá USD→CNY dùng cho mọi giá trị *_cny trong response đó.

Ngữ nghĩa báo cáo

logicalModel là model logic công khai mà phía gọi yêu cầu.
modelVendor là nhà cung cấp model công khai, không phải tuyến vật lý bị ẩn.
scene là ngữ cảnh yêu cầu công khai được suy ra từ endpoint hoặc loại tác vụ.
accessChannel=platform nghĩa là yêu cầu được tính phí qua kênh nền tảng của LemonData.
accessChannel=byok nghĩa là yêu cầu dùng khóa upstream provider của riêng bạn.

Phản hồi chỉ trả về các trường chi phí và báo cáo công khai. Chi tiết routing nội bộ và metadata provider vật lý vẫn bị ẩn.

Lưu ý về phân trang chi phí

/usage có phân trang. /billing hiện là endpoint tổng hợp và không trả về metadata phân trang kiểu page / limit. Nếu bạn cần bản ghi chi tiết từng dòng, hãy dùng /usage.

Ví dụ nhanh

Bắt đầu bằng cách liệt kê các API key khả dụng cho management token hiện tại.

curl "https://api.lemondata.cc/v1/management/api-keys" \
  -H "Authorization: Bearer mt-your-management-token"

{
  "object": "list",
  "data": [
    {
      "id": "key_abc123def456",
      "name": "Backend Worker",
      "key_prefix": "sk-abc123...",
      "status": "active",
      "limit_amount": 500.0,
      "limit_amount_cny": 3600.0,
      "used_amount": 148.25,
      "used_amount_cny": 1067.4,
      "exchange_rate": 7.2,
      "models": ["gpt-4o-mini", "claude-3-7-sonnet"],
      "expires_at": "2026-04-30T00:00:00.000Z",
      "last_used_at": "2026-03-27T08:12:45.000Z",
      "created_at": "2026-03-01T10:00:00.000Z"
    }
  ]
}

Cốt lõi

Văn bản

Tệp và lô

Hình ảnh và phương tiện

Tác vụ bất đồng bộ

Gemini gốc

Quản lý

Tổng quan

Endpoint khả dụng

Hợp đồng bộ lọc usage

Hợp đồng body API key

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

Hợp đồng tiền tệ

Ngữ nghĩa báo cáo

Lưu ý về phân trang chi phí

Ví dụ nhanh

Bước tiếp theo

Cốt lõi

Văn bản

Tệp và lô

Hình ảnh và phương tiện

Tác vụ bất đồng bộ

Gemini gốc

Quản lý

​Tổng quan

​Endpoint khả dụng

​Hợp đồng bộ lọc usage

​Hợp đồng body API key

​POST /v1/management/api-keys

​PATCH /v1/management/api-keys/

​Hợp đồng tiền tệ

​Ngữ nghĩa báo cáo

​Lưu ý về phân trang chi phí

​Ví dụ nhanh

​Bước tiếp theo

Tổng quan

Endpoint khả dụng

Hợp đồng bộ lọc usage

Hợp đồng body API key

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

Hợp đồng tiền tệ

Ngữ nghĩa báo cáo

Lưu ý về phân trang chi phí

Ví dụ nhanh

Bước tiếp theo