ProxyCast 提供远程管理 API，用于配置和监控服务。
所有管理 API 请求需要在 Authorization 头中提供密钥：
Authorization: Bearer your-secret-key
管理 API 的访问受以下配置控制：
| 配置项 | 说明 |
|---|---|
secret_key | 管理密钥，为空时禁用所有管理端点（返回 404） |
allow_remote | 是否允许远程访问，为 false 时仅允许 localhost |
获取服务器状态信息。
GET /v0/management/status
Authorization: Bearer your-secret-key
{
"status": "running",
"version": "1.0.0",
"uptime_seconds": 3600,
"tls_enabled": false,
"active_credentials": 5,
"total_requests": 1234,
"providers": {
"kiro": {
"enabled": true,
"credentials_count": 2
},
"gemini": {
"enabled": true,
"credentials_count": 1
}
}
}
GET /v0/management/credentials
Authorization: Bearer your-secret-key
{
"credentials": [
{
"id": "kiro-main",
"provider": "kiro",
"type": "oauth",
"status": "valid",
"expires_at": "2025-01-01T00:00:00Z",
"disabled": false
},
{
"id": "gemini-key-1",
"provider": "gemini_api_key",
"type": "api_key",
"status": "valid",
"disabled": false,
"excluded_models": ["gemini-2.5-pro"]
}
]
}
POST /v0/management/credentials
Authorization: Bearer your-secret-key
Content-Type: application/json
{
"provider": "kiro",
"id": "kiro-new",
"token_file": "kiro/new-token.json"
}
{
"provider": "openai",
"id": "openai-new",
"api_key": "sk-xxx...",
"base_url": "https://api.openai.com/v1"
}
{
"provider": "gemini_api_key",
"id": "gemini-key-new",
"api_key": "AIzaSy...",
"base_url": "https://generativelanguage.googleapis.com",
"excluded_models": ["gemini-2.5-pro", "*-preview"]
}
{
"success": true,
"credential_id": "kiro-new"
}
DELETE /v0/management/credentials/{credential_id}
Authorization: Bearer your-secret-key
{
"success": true
}
GET /v0/management/config
Authorization: Bearer your-secret-key
{
"server": {
"host": "127.0.0.1",
"port": 8999,
"tls": {
"enable": false
}
},
"routing": {
"default_provider": "kiro"
},
"quota_exceeded": {
"switch_project": true,
"switch_preview_model": true,
"cooldown_seconds": 300
}
}
PUT /v0/management/config
Authorization: Bearer your-secret-key
Content-Type: application/json
{
"routing": {
"default_provider": "gemini"
},
"quota_exceeded": {
"cooldown_seconds": 600
}
}
{
"success": true,
"restart_required": false
}
注意: 某些配置更改（如 TLS、端口）需要重启服务器才能生效。
密钥无效或缺失：
{
"error": {
"message": "Invalid or missing secret key",
"type": "authentication_error",
"code": "invalid_api_key"
}
}
远程访问被禁止：
{
"error": {
"message": "Remote access not allowed",
"type": "permission_error",
"code": "remote_access_denied"
}
}
管理 API 已禁用（secret_key 为空）：
{
"error": {
"message": "Management API is disabled",
"type": "not_found_error",
"code": "endpoint_not_found"
}
}
# 获取状态
curl http://127.0.0.1:8999/v0/management/status \
-H "Authorization: Bearer your-secret-key"
# 获取凭证列表
curl http://127.0.0.1:8999/v0/management/credentials \
-H "Authorization: Bearer your-secret-key"
# 添加凭证
curl http://127.0.0.1:8999/v0/management/credentials \
-H "Authorization: Bearer your-secret-key" \
-H "Content-Type: application/json" \
-d '{"provider": "openai", "id": "openai-new", "api_key": "sk-xxx"}'
import requests
BASE_URL = "http://127.0.0.1:8999"
SECRET_KEY = "your-secret-key"
headers = {
"Authorization": f"Bearer {SECRET_KEY}",
"Content-Type": "application/json"
}
# 获取状态
response = requests.get(f"{BASE_URL}/v0/management/status", headers=headers)
print(response.json())
# 添加凭证
credential = {
"provider": "openai",
"id": "openai-new",
"api_key": "sk-xxx"
}
response = requests.post(
f"{BASE_URL}/v0/management/credentials",
headers=headers,
json=credential
)
print(response.json())