Cập nhật API Key

PATCH /api/open/v1/keys/:id

Tham số yêu cầu

Chỉ các trường có trong body yêu cầu mới được cập nhật; các trường bị bỏ qua giữ nguyên. Cần ít nhất một trường có thể sửa: body rỗng, null hoặc {} trả về 400.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
id	path	integer	Có	ID của Key, số nguyên dương
name	body	string	Không	Tên; không được để trống sau khi bỏ khoảng trắng, tối đa 50 ký tự (ký tự, không phải byte)
status	body	integer	Không	1 bật, 2 tắt; giá trị khác trả về 400 (3 / 4 do hệ thống tự đặt)
expired_time	body	integer	Không	Thời gian hết hạn, giây unix; 0 / -1 nghĩa là không bao giờ hết hạn
remain_amount	body	number	Không	Số tiền khả dụng, theo tiền tệ của trang, hai chữ số thập phân; không được âm và không được vượt mức tối đa
unlimited	body	boolean	Không	Có phải Key không giới hạn hạn mức hay không
model_limits_enabled	body	boolean	Không	Có bật danh sách cho phép mô hình hay không
model_limits	body	string	Không	Các mô hình được phép, phân tách bằng dấu phẩy
allow_ips	body	string	Không	Các IP được phép, mỗi IP một dòng; chuỗi rỗng nghĩa là không giới hạn

status chỉ nhận 1 (bật) hoặc 2 (tắt). Bật yêu cầu Key phải dùng được sau lần cập nhật này: chưa hết hạn (expired_time là -1 hoặc ở tương lai) và không giới hạn hạn mức hoặc remain_amount > 0; nếu không sẽ trả về 400. Bạn có thể gửi các trường cùng nhau, ví dụ {"status": 1, "expired_time": 1767225600}. Tắt được từ mọi trạng thái, và status chỉ định rõ luôn được ưu tiên hơn việc tự động khôi phục.

Ví dụ yêu cầu

Nạp thêm tiền cho Key đã hết (Key tự động trở lại trạng thái bật):

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"remain_amount": 20.00}'

Gia hạn thời gian hết hạn:

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expired_time": 1767225600}'

Tắt Key (các yêu cầu dùng Key này bị từ chối cho đến khi bật lại):

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 2}'

Bật lại Key, đồng thời gia hạn trong cùng yêu cầu để chắc chắn Key dùng được:

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 1, "expired_time": 1767225600}'

Ví dụ phản hồi

Trả về đối tượng Key đã cập nhật với key bị che:

{
  "success": true,
  "message": "",
  "data": {
    "id": 12,
    "name": "bot",
    "key": "sk-abcd**********wxyz",
    "status": 1,
    "created_time": 1729000000,
    "accessed_time": 1729000000,
    "expired_time": -1,
    "remain_amount": 20.00,
    "unlimited": false,
    "used_amount": 10.00,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": ""
  }
}

Mô tả các trường xem tại Đối tượng Key.

Lỗi

HTTP	code	Tình huống
400	invalid_request	id không phải số nguyên dương, hoặc body không phải JSON hợp lệ
400	invalid_request	Body rỗng, null hoặc không có trường nào có thể sửa
400	invalid_request	status không phải 1 hoặc 2 (trạng thái 3 / 4 do hệ thống tự đặt)
400	invalid_request	Gửi status: 1 khi Key vẫn còn hết hạn hoặc hết hạn mức; hãy gia hạn expired_time, nạp thêm remain_amount hoặc đặt unlimited (có thể gửi cùng trong một yêu cầu)
400	invalid_request	Tên dài hơn 50 ký tự, hoặc remain_amount âm hay vượt mức tối đa
400	invalid_request	expired_time không ở tương lai (và không phải 0 / -1), hoặc muộn hơn 9999-12-31
400	invalid_request	Chỉ gửi remain_amount cho Key không giới hạn hạn mức, hoặc đổi Key không giới hạn sang có giới hạn mà không gửi remain_amount
404	not_found	Key không tồn tại hoặc không thuộc về bạn

Các mã lỗi chung khác xem tại Lỗi API nền tảng.

Lưu ý

• Chỉ gửi remain_amount: có hiệu lực ngay với Key có hạn mức giới hạn; trả về 400 với Key không giới hạn hạn mức, khi đó bạn phải gửi kèm "unlimited": false.
• "unlimited": false mà không có remain_amount: trả về 400 với Key không giới hạn (để số dư không bị đặt về 0 một cách âm thầm); Key vốn đã có giới hạn giữ nguyên số dư hiện tại.
• Key đã hết hạn (3) hoặc đã hết hạn mức (4) sẽ tự động trở lại trạng thái bật (1) khi lần cập nhật này làm nó dùng được trở lại (expired_time được gia hạn, remain_amount dương hoặc unlimited). Việc tự động khôi phục chỉ áp dụng khi không gửi status.
• 2 là trạng thái khi bạn tự tắt Key. Nó không bao giờ tự khôi phục; hãy gửi status: 1 để bật lại. Khi Key không ở trạng thái 1, các lệnh gọi mô hình bằng Key đó sẽ bị từ chối.
• Mọi trường đều được kiểm tra trước khi ghi: nếu bất kỳ trường nào không hợp lệ, trả về 400 và không trường nào bị thay đổi.
• Việc cập nhật Key qua API nền tảng được ghi vào nhật ký kiểm toán.