建立 API Key

POST /api/open/v1/keys

請求參數

請求主體為 JSON，Content-Type: application/json。驗證規則與控制台建立 Key 一致。

欄位	類型	必填	預設值	說明
`name`	string	是	—	名稱，最長 50 個字元（按字元計，不是位元組）；不能為空
`remain_amount`	number	否	`0`	可用金額，站點幣別，兩位小數；`unlimited` 為 `false` 時生效，不能為負數且不能超過上限
`unlimited`	boolean	否	`false`	是否無限額度
`expired_time`	integer	否	`-1`	過期時間，unix 秒；省略、`0`、`-1` 均表示永不過期；其他值必須是未來時間且不超過 9999-12-31
`model_limits_enabled`	boolean	否	`false`	是否啟用模型白名單
`model_limits`	string	否	`""`	允許的模型，以半形逗號分隔
`allow_ips`	string	否	—	允許的 IP，以換行分隔；不傳或空字串表示不限制

請求範例

curl -X POST https://www.routeapi.ai/api/open/v1/keys \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bot",
    "remain_amount": 5.00,
    "unlimited": false,
    "expired_time": -1,
    "model_limits_enabled": true,
    "model_limits": "gpt-4o"
  }'

回應範例

{
  "success": true,
  "message": "",
  "data": {
    "id": 13,
    "name": "bot",
    "key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": 1,
    "created_time": 1729000000,
    "accessed_time": 1729000000,
    "expired_time": -1,
    "remain_amount": 5.00,
    "unlimited": false,
    "used_amount": 0.00,
    "model_limits_enabled": true,
    "model_limits": "gpt-4o",
    "allow_ips": ""
  }
}

欄位說明見 Key 物件。

錯誤

HTTP	code	情境
400	`invalid_request`	請求主體不是合法 JSON，或為空 / `null`
400	`invalid_request`	`name` 缺失、為空白，或超過 50 個字元
400	`invalid_request`	`expired_time` 不是未來時間（且不是 `0` / `-1`），或超出 9999-12-31（例如誤傳毫秒時間戳）
400	`invalid_request`	已達到每位使用者的 Key 數量上限
400	`invalid_request`	`unlimited` 為 `false` 時 `remain_amount` 為負數或超過上限

其他通用錯誤碼見開放平台 API 錯誤。

說明

unlimited 為 true 時忽略 remain_amount。
透過開放平台 API 建立 Key 會記錄稽核日誌。