docs: remove MANAGEMENT_API documentation files (EN and CN)
- Deleted `MANAGEMENT_API.md` and `MANAGEMENT_API_CN.md` as they are no longer necessary. - Streamlined project documentation by removing redundant API details already covered elsewhere.
This commit is contained in:
Luis Pater
@@ -1,827 +0,0 @@
|
|||||||
# Management API
|
|
||||||
|
|
||||||
Base path: `http://localhost:8317/v0/management`
|
|
||||||
|
|
||||||
This API manages the CLI Proxy API’s runtime configuration and authentication files. All changes are persisted to the YAML config file and hot‑reloaded by the service.
|
|
||||||
|
|
||||||
Note: The following options cannot be modified via API and must be set in the config file (restart if needed):
|
|
||||||
- `allow-remote-management`
|
|
||||||
- `remote-management-key` (if plaintext is detected at startup, it is automatically bcrypt‑hashed and written back to the config)
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
|
|
||||||
- All requests (including localhost) must provide a valid management key.
|
|
||||||
- Remote access requires enabling remote management in the config: `allow-remote-management: true`.
|
|
||||||
- Provide the management key (in plaintext) via either:
|
|
||||||
- `Authorization: Bearer <plaintext-key>`
|
|
||||||
- `X-Management-Key: <plaintext-key>`
|
|
||||||
|
|
||||||
Additional notes:
|
|
||||||
- If `remote-management.secret-key` is empty, the entire Management API is disabled (all `/v0/management` routes return 404).
|
|
||||||
- For remote IPs, 5 consecutive authentication failures trigger a temporary ban (~30 minutes) before further attempts are allowed.
|
|
||||||
|
|
||||||
If a plaintext key is detected in the config at startup, it will be bcrypt‑hashed and written back to the config file automatically.
|
|
||||||
|
|
||||||
## Request/Response Conventions
|
|
||||||
|
|
||||||
- Content-Type: `application/json` (unless otherwise noted).
|
|
||||||
- Boolean/int/string updates: request body is `{ "value": <type> }`.
|
|
||||||
- Array PUT: either a raw array (e.g. `["a","b"]`) or `{ "items": [ ... ] }`.
|
|
||||||
- Array PATCH: supports `{ "old": "k1", "new": "k2" }` or `{ "index": 0, "value": "k2" }`.
|
|
||||||
- Object-array PATCH: supports matching by index or by key field (specified per endpoint).
|
|
||||||
|
|
||||||
## Endpoints
|
|
||||||
|
|
||||||
### Usage Statistics
|
|
||||||
- GET `/usage` — Retrieve aggregated in-memory request metrics
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"usage": {
|
|
||||||
"total_requests": 24,
|
|
||||||
"success_count": 22,
|
|
||||||
"failure_count": 2,
|
|
||||||
"total_tokens": 13890,
|
|
||||||
"requests_by_day": {
|
|
||||||
"2024-05-20": 12
|
|
||||||
},
|
|
||||||
"requests_by_hour": {
|
|
||||||
"09": 4,
|
|
||||||
"18": 8
|
|
||||||
},
|
|
||||||
"tokens_by_day": {
|
|
||||||
"2024-05-20": 9876
|
|
||||||
},
|
|
||||||
"tokens_by_hour": {
|
|
||||||
"09": 1234,
|
|
||||||
"18": 865
|
|
||||||
},
|
|
||||||
"apis": {
|
|
||||||
"POST /v1/chat/completions": {
|
|
||||||
"total_requests": 12,
|
|
||||||
"total_tokens": 9021,
|
|
||||||
"models": {
|
|
||||||
"gpt-4o-mini": {
|
|
||||||
"total_requests": 8,
|
|
||||||
"total_tokens": 7123,
|
|
||||||
"details": [
|
|
||||||
{
|
|
||||||
"timestamp": "2024-05-20T09:15:04.123456Z",
|
|
||||||
"tokens": {
|
|
||||||
"input_tokens": 523,
|
|
||||||
"output_tokens": 308,
|
|
||||||
"reasoning_tokens": 0,
|
|
||||||
"cached_tokens": 0,
|
|
||||||
"total_tokens": 831
|
|
||||||
}
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"failed_requests": 2
|
|
||||||
}
|
|
||||||
```
|
|
||||||
- Notes:
|
|
||||||
- Statistics are recalculated for every request that reports token usage; data resets when the server restarts.
|
|
||||||
- Hourly counters fold all days into the same hour bucket (`00`–`23`).
|
|
||||||
- The top-level `failed_requests` repeats `usage.failure_count` for convenience when polling.
|
|
||||||
|
|
||||||
### Config
|
|
||||||
- GET `/config` — Get the full config
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/config
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{"debug":true,"proxy-url":"","api-keys":["1...5","JS...W"],"quota-exceeded":{"switch-project":true,"switch-preview-model":true},"gemini-api-key":[{"api-key":"AI...01","base-url":"https://generativelanguage.googleapis.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":""},{"api-key":"AI...02","proxy-url":"socks5://proxy.example.com:1080"}],"gl-api-key":["AI...01","AI...02"],"request-log":true,"request-retry":3,"claude-api-key":[{"api-key":"cr...56","base-url":"https://example.com/api","proxy-url":"socks5://proxy.example.com:1080","models":[{"name":"claude-3-5-sonnet-20241022","alias":"claude-sonnet-latest"}]},{"api-key":"cr...e3","base-url":"http://example.com:3000/api","proxy-url":""},{"api-key":"sk-...q2","base-url":"https://example.com","proxy-url":""}],"codex-api-key":[{"api-key":"sk...01","base-url":"https://example/v1","proxy-url":""}],"openai-compatibility":[{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk...01","proxy-url":""}],"models":[{"name":"moonshotai/kimi-k2:free","alias":"kimi-k2"}]},{"name":"iflow","base-url":"https://apis.iflow.cn/v1","api-key-entries":[{"api-key":"sk...7e","proxy-url":"socks5://proxy.example.com:1080"}],"models":[{"name":"deepseek-v3.1","alias":"deepseek-v3.1"},{"name":"glm-4.5","alias":"glm-4.5"},{"name":"kimi-k2","alias":"kimi-k2"}]}]}
|
|
||||||
```
|
|
||||||
- Notes:
|
|
||||||
- The response includes a sanitized `gl-api-key` list derived from the detailed `gemini-api-key` entries.
|
|
||||||
- When no configuration is loaded yet the handler returns `{}`.
|
|
||||||
|
|
||||||
### Debug
|
|
||||||
- GET `/debug` — Get the current debug state
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/debug
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "debug": false }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/debug` — Set debug (boolean)
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":true}' \
|
|
||||||
http://localhost:8317/v0/management/debug
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Config YAML
|
|
||||||
- GET `/config.yaml` — Download the persisted YAML file as-is
|
|
||||||
- Response headers:
|
|
||||||
- `Content-Type: application/yaml; charset=utf-8`
|
|
||||||
- `Cache-Control: no-store`
|
|
||||||
- Response body: raw YAML stream preserving comments/formatting.
|
|
||||||
- PUT `/config.yaml` — Replace the config with a YAML document
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/yaml' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
--data-binary @config.yaml \
|
|
||||||
http://localhost:8317/v0/management/config.yaml
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "ok": true, "changed": ["config"] }
|
|
||||||
```
|
|
||||||
- Notes:
|
|
||||||
- The server validates the YAML by loading it before persisting; invalid configs return `422` with `{ "error": "invalid_config", "message": "..." }`.
|
|
||||||
- Write failures return `500` with `{ "error": "write_failed", "message": "..." }`.
|
|
||||||
|
|
||||||
### Logging to File
|
|
||||||
- GET `/logging-to-file` — Check whether file logging is enabled
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "logging-to-file": true }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/logging-to-file` — Enable or disable file logging
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":false}' \
|
|
||||||
http://localhost:8317/v0/management/logging-to-file
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Log Files
|
|
||||||
- GET `/logs` — Stream recent log lines
|
|
||||||
- Query params:
|
|
||||||
- `after` (optional): Unix timestamp; only lines newer than this are returned.
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"lines": ["2024-05-20 12:00:00 info request accepted"],
|
|
||||||
"line-count": 125,
|
|
||||||
"latest-timestamp": 1716206400
|
|
||||||
}
|
|
||||||
```
|
|
||||||
- Notes:
|
|
||||||
- Requires file logging to be enabled; otherwise returns `{ "error": "logging to file disabled" }` with `400`.
|
|
||||||
- When no log file exists yet the response contains empty `lines` and `line-count: 0`.
|
|
||||||
- DELETE `/logs` — Remove rotated log files and truncate the active log
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "success": true, "message": "Logs cleared successfully", "removed": 3 }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Usage Statistics Toggle
|
|
||||||
- GET `/usage-statistics-enabled` — Check whether telemetry collection is active
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "usage-statistics-enabled": true }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/usage-statistics-enabled` — Enable or disable collection
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":true}' \
|
|
||||||
http://localhost:8317/v0/management/usage-statistics-enabled
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Proxy Server URL
|
|
||||||
- GET `/proxy-url` — Get the proxy URL string
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/proxy-url
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "proxy-url": "socks5://user:pass@127.0.0.1:1080/" }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/proxy-url` — Set the proxy URL string
|
|
||||||
- Request (PUT):
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":"socks5://user:pass@127.0.0.1:1080/"}' \
|
|
||||||
http://localhost:8317/v0/management/proxy-url
|
|
||||||
```
|
|
||||||
- Request (PATCH):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":"http://127.0.0.1:8080"}' \
|
|
||||||
http://localhost:8317/v0/management/proxy-url
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/proxy-url` — Clear the proxy URL
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE http://localhost:8317/v0/management/proxy-url
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Quota Exceeded Behavior
|
|
||||||
- GET `/quota-exceeded/switch-project`
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-project
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "switch-project": true }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/quota-exceeded/switch-project` — Boolean
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":false}' \
|
|
||||||
http://localhost:8317/v0/management/quota-exceeded/switch-project
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- GET `/quota-exceeded/switch-preview-model`
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-preview-model
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "switch-preview-model": true }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/quota-exceeded/switch-preview-model` — Boolean
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":true}' \
|
|
||||||
http://localhost:8317/v0/management/quota-exceeded/switch-preview-model
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### API Keys (proxy service auth)
|
|
||||||
These endpoints update the inline `config-api-key` provider inside the `auth.providers` section of the configuration. Legacy top-level `api-keys` remain in sync automatically.
|
|
||||||
- GET `/api-keys` — Return the full list
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/api-keys
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "api-keys": ["k1","k2","k3"] }
|
|
||||||
```
|
|
||||||
- PUT `/api-keys` — Replace the full list
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '["k1","k2","k3"]' \
|
|
||||||
http://localhost:8317/v0/management/api-keys
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/api-keys` — Modify one item (`old/new` or `index/value`)
|
|
||||||
- Request (by old/new):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"old":"k2","new":"k2b"}' \
|
|
||||||
http://localhost:8317/v0/management/api-keys
|
|
||||||
```
|
|
||||||
- Request (by index/value):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"index":0,"value":"k1b"}' \
|
|
||||||
http://localhost:8317/v0/management/api-keys
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/api-keys` — Delete one (`?value=` or `?index=`)
|
|
||||||
- Request (by value):
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?value=k1'
|
|
||||||
```
|
|
||||||
- Request (by index):
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?index=0'
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Gemini API Key
|
|
||||||
- GET `/gemini-api-key`
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/gemini-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"gemini-api-key": [
|
|
||||||
{"api-key":"AIzaSy...01","base-url":"https://generativelanguage.googleapis.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":""},
|
|
||||||
{"api-key":"AIzaSy...02","proxy-url":"socks5://proxy.example.com:1080"}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
- PUT `/gemini-api-key`
|
|
||||||
- Request (array form):
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '[{"api-key":"AIzaSy-1","headers":{"X-Custom-Header":"vendor-value"}},{"api-key":"AIzaSy-2","base-url":"https://custom.example.com"}]' \
|
|
||||||
http://localhost:8317/v0/management/gemini-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/gemini-api-key`
|
|
||||||
- Request (update by index):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"index":0,"value":{"api-key":"AIzaSy-1","base-url":"https://custom.example.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":""}}' \
|
|
||||||
http://localhost:8317/v0/management/gemini-api-key
|
|
||||||
```
|
|
||||||
- Request (update by api-key match):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"match":"AIzaSy-1","value":{"api-key":"AIzaSy-1","headers":{"X-Custom-Header":"custom-value"},"proxy-url":"socks5://proxy.example.com:1080"}}' \
|
|
||||||
http://localhost:8317/v0/management/gemini-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/gemini-api-key`
|
|
||||||
- Request (by api-key):
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE \
|
|
||||||
'http://localhost:8317/v0/management/gemini-api-key?api-key=AIzaSy-1'
|
|
||||||
```
|
|
||||||
- Request (by index):
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE \
|
|
||||||
'http://localhost:8317/v0/management/gemini-api-key?index=0'
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Generative Language API Key (Legacy Alias)
|
|
||||||
- GET `/generative-language-api-key`
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/generative-language-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "generative-language-api-key": ["AIzaSy...01","AIzaSy...02"] }
|
|
||||||
```
|
|
||||||
- PUT `/generative-language-api-key`
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '["AIzaSy-1","AIzaSy-2"]' \
|
|
||||||
http://localhost:8317/v0/management/generative-language-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/generative-language-api-key`
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"old":"AIzaSy-1","new":"AIzaSy-1b"}' \
|
|
||||||
http://localhost:8317/v0/management/generative-language-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/generative-language-api-key`
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/generative-language-api-key?value=AIzaSy-2'
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- Notes:
|
|
||||||
- This endpoint mirrors the key-only view of `gemini-api-key`.
|
|
||||||
|
|
||||||
### Codex API KEY (object array)
|
|
||||||
- GET `/codex-api-key` — List all
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/codex-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "codex-api-key": [ { "api-key": "sk-a", "base-url": "", "proxy-url": "" } ] }
|
|
||||||
```
|
|
||||||
- PUT `/codex-api-key` — Replace the list
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '[{"api-key":"sk-a","proxy-url":"socks5://proxy.example.com:1080"},{"api-key":"sk-b","base-url":"https://c.example.com","proxy-url":""}]' \
|
|
||||||
http://localhost:8317/v0/management/codex-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/codex-api-key` — Modify one (by `index` or `match`)
|
|
||||||
- Request (by index):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com","proxy-url":""}}' \
|
|
||||||
http://localhost:8317/v0/management/codex-api-key
|
|
||||||
```
|
|
||||||
- Request (by match):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":"","proxy-url":"socks5://proxy.example.com:1080"}}' \
|
|
||||||
http://localhost:8317/v0/management/codex-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/codex-api-key` — Delete one (`?api-key=` or `?index=`)
|
|
||||||
- Request (by api-key):
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?api-key=sk-b2'
|
|
||||||
```
|
|
||||||
- Request (by index):
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?index=0'
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Request Retry Count
|
|
||||||
- GET `/request-retry` — Get integer
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/request-retry
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "request-retry": 3 }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/request-retry` — Set integer
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":5}' \
|
|
||||||
http://localhost:8317/v0/management/request-retry
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Request Log
|
|
||||||
- GET `/request-log` — Get boolean
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/request-log
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "request-log": false }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/request-log` — Set boolean
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":true}' \
|
|
||||||
http://localhost:8317/v0/management/request-log
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Claude API KEY (object array)
|
|
||||||
- GET `/claude-api-key` — List all
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/claude-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "claude-api-key": [ { "api-key": "sk-a", "base-url": "", "proxy-url": "" } ] }
|
|
||||||
```
|
|
||||||
- PUT `/claude-api-key` — Replace the list
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '[{"api-key":"sk-a","proxy-url":"socks5://proxy.example.com:1080"},{"api-key":"sk-b","base-url":"https://c.example.com","proxy-url":""}]' \
|
|
||||||
http://localhost:8317/v0/management/claude-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/claude-api-key` — Modify one (by `index` or `match`)
|
|
||||||
- Request (by index):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com","proxy-url":""}}' \
|
|
||||||
http://localhost:8317/v0/management/claude-api-key
|
|
||||||
```
|
|
||||||
- Request (by match):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":"","proxy-url":"socks5://proxy.example.com:1080"}}' \
|
|
||||||
http://localhost:8317/v0/management/claude-api-key
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/claude-api-key` — Delete one (`?api-key=` or `?index=`)
|
|
||||||
- Request (by api-key):
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?api-key=sk-b2'
|
|
||||||
```
|
|
||||||
- Request (by index):
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?index=0'
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### OpenAI Compatibility Providers (object array)
|
|
||||||
- GET `/openai-compatibility` — List all
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/openai-compatibility
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "openai-compatibility": [ { "name": "openrouter", "base-url": "https://openrouter.ai/api/v1", "api-key-entries": [ { "api-key": "sk", "proxy-url": "" } ], "models": [] } ] }
|
|
||||||
```
|
|
||||||
- PUT `/openai-compatibility` — Replace the list
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '[{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[{"name":"m","alias":"a"}]}]' \
|
|
||||||
http://localhost:8317/v0/management/openai-compatibility
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/openai-compatibility` — Modify one (by `index` or `name`)
|
|
||||||
- Request (by name):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"name":"openrouter","value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[]}}' \
|
|
||||||
http://localhost:8317/v0/management/openai-compatibility
|
|
||||||
```
|
|
||||||
- Request (by index):
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"index":0,"value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[]}}' \
|
|
||||||
http://localhost:8317/v0/management/openai-compatibility
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- Notes:
|
|
||||||
- Legacy `api-keys` input remains accepted; keys are migrated into `api-key-entries` automatically so the legacy field will eventually remain empty in responses.
|
|
||||||
- DELETE `/openai-compatibility` — Delete (`?name=` or `?index=`)
|
|
||||||
- Request (by name):
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?name=openrouter'
|
|
||||||
```
|
|
||||||
- Request (by index):
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?index=0'
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Auth File Management
|
|
||||||
|
|
||||||
Manage JSON token files under `auth-dir`: list, download, upload, delete.
|
|
||||||
|
|
||||||
- GET `/auth-files` — List
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/auth-files
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "files": [ { "name": "acc1.json", "size": 1234, "modtime": "2025-08-30T12:34:56Z", "type": "google", "email": "user@example.com" } ] }
|
|
||||||
```
|
|
||||||
- Notes:
|
|
||||||
- `modtime` is returned in RFC3339 format; when metadata includes an email it is surfaced.
|
|
||||||
|
|
||||||
- GET `/auth-files/download?name=<file.json>` — Download a single file
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -OJ 'http://localhost:8317/v0/management/auth-files/download?name=acc1.json'
|
|
||||||
```
|
|
||||||
|
|
||||||
- POST `/auth-files` — Upload
|
|
||||||
- Request (multipart):
|
|
||||||
```bash
|
|
||||||
curl -X POST -F 'file=@/path/to/acc1.json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
http://localhost:8317/v0/management/auth-files
|
|
||||||
```
|
|
||||||
- Request (raw JSON):
|
|
||||||
```bash
|
|
||||||
curl -X POST -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d @/path/to/acc1.json \
|
|
||||||
'http://localhost:8317/v0/management/auth-files?name=acc1.json'
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- Notes:
|
|
||||||
- The core auth manager must be active; otherwise the API returns `503` with `{ "error": "core auth manager unavailable" }`.
|
|
||||||
- Uploaded filenames must end with `.json`.
|
|
||||||
|
|
||||||
- DELETE `/auth-files?name=<file.json>` — Delete a single file
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/auth-files?name=acc1.json'
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- DELETE `/auth-files?all=true` — Delete all `.json` files under `auth-dir`
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/auth-files?all=true'
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "deleted": 3 }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Login/OAuth URLs
|
|
||||||
|
|
||||||
These endpoints initiate provider login flows and return a URL to open in a browser. Tokens are saved under `auths/` once the flow completes.
|
|
||||||
|
|
||||||
For Anthropic, Codex, Gemini CLI, and iFlow you can append `?is_webui=true` to reuse the embedded callback forwarder when launching from the management UI.
|
|
||||||
|
|
||||||
- GET `/anthropic-auth-url` — Start Anthropic (Claude) login
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
http://localhost:8317/v0/management/anthropic-auth-url
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "url": "https://...", "state": "anth-1716206400" }
|
|
||||||
```
|
|
||||||
- Notes:
|
|
||||||
- Add `?is_webui=true` when triggering from the built-in UI to reuse the local callback service.
|
|
||||||
|
|
||||||
- GET `/codex-auth-url` — Start Codex login
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
http://localhost:8317/v0/management/codex-auth-url
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "url": "https://...", "state": "codex-1716206400" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- GET `/gemini-cli-auth-url` — Start Google (Gemini CLI) login
|
|
||||||
- Query params:
|
|
||||||
- `project_id` (optional): Google Cloud project ID.
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
'http://localhost:8317/v0/management/gemini-cli-auth-url?project_id=<PROJECT_ID>'
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "url": "https://...", "state": "gem-1716206400" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- GET `/qwen-auth-url` — Start Qwen login (device flow)
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
http://localhost:8317/v0/management/qwen-auth-url
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "url": "https://...", "state": "gem-1716206400" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- GET `/iflow-auth-url` — Start iFlow login
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
http://localhost:8317/v0/management/iflow-auth-url
|
|
||||||
```
|
|
||||||
- Response:
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "url": "https://...", "state": "ifl-1716206400" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- GET `/get-auth-status?state=<state>` — Poll OAuth flow status
|
|
||||||
- Request:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
'http://localhost:8317/v0/management/get-auth-status?state=<STATE_FROM_AUTH_URL>'
|
|
||||||
```
|
|
||||||
- Response examples:
|
|
||||||
```json
|
|
||||||
{ "status": "wait" }
|
|
||||||
{ "status": "ok" }
|
|
||||||
{ "status": "error", "error": "Authentication failed" }
|
|
||||||
```
|
|
||||||
|
|
||||||
## Error Responses
|
|
||||||
|
|
||||||
Generic error format:
|
|
||||||
- 400 Bad Request: `{ "error": "invalid body" }`
|
|
||||||
- 401 Unauthorized: `{ "error": "missing management key" }` or `{ "error": "invalid management key" }`
|
|
||||||
- 403 Forbidden: `{ "error": "remote management disabled" }`
|
|
||||||
- 404 Not Found: `{ "error": "item not found" }` or `{ "error": "file not found" }`
|
|
||||||
- 422 Unprocessable Entity: `{ "error": "invalid_config", "message": "..." }`
|
|
||||||
- 500 Internal Server Error: `{ "error": "failed to save config: ..." }`
|
|
||||||
- 503 Service Unavailable: `{ "error": "core auth manager unavailable" }`
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
|
|
||||||
- Changes are written back to the YAML config file and hot‑reloaded by the file watcher and clients.
|
|
||||||
- `allow-remote-management` and `remote-management-key` cannot be changed via the API; configure them in the config file.
|
|
||||||
@@ -1,827 +0,0 @@
|
|||||||
# 管理 API
|
|
||||||
|
|
||||||
基础路径：`http://localhost:8317/v0/management`
|
|
||||||
|
|
||||||
该 API 用于管理 CLI Proxy API 的运行时配置与认证文件。所有变更会持久化写入 YAML 配置文件，并由服务自动热重载。
|
|
||||||
|
|
||||||
注意：以下选项不能通过 API 修改，需在配置文件中设置（如有必要可重启）：
|
|
||||||
- `allow-remote-management`
|
|
||||||
- `remote-management-key`（若在启动时检测到明文，会自动进行 bcrypt 加密并写回配置）
|
|
||||||
|
|
||||||
## 认证
|
|
||||||
|
|
||||||
- 所有请求（包括本地访问）都必须提供有效的管理密钥.
|
|
||||||
- 远程访问需要在配置文件中开启远程访问： `allow-remote-management: true`
|
|
||||||
- 通过以下任意方式提供管理密钥（明文）：
|
|
||||||
- `Authorization: Bearer <plaintext-key>`
|
|
||||||
- `X-Management-Key: <plaintext-key>`
|
|
||||||
|
|
||||||
若在启动时检测到配置中的管理密钥为明文，会自动使用 bcrypt 加密并回写到配置文件中。
|
|
||||||
|
|
||||||
其它说明：
|
|
||||||
- 若 `remote-management.secret-key` 为空，则管理 API 整体被禁用（所有 `/v0/management` 路由均返回 404）。
|
|
||||||
- 对于远程 IP，连续 5 次认证失败会触发临时封禁（约 30 分钟）。
|
|
||||||
|
|
||||||
## 请求/响应约定
|
|
||||||
|
|
||||||
- Content-Type：`application/json`（除非另有说明）。
|
|
||||||
- 布尔/整数/字符串更新：请求体为 `{ "value": <type> }`。
|
|
||||||
- 数组 PUT：既可使用原始数组（如 `["a","b"]`），也可使用 `{ "items": [ ... ] }`。
|
|
||||||
- 数组 PATCH：支持 `{ "old": "k1", "new": "k2" }` 或 `{ "index": 0, "value": "k2" }`。
|
|
||||||
- 对象数组 PATCH：支持按索引或按关键字段匹配（各端点中单独说明）。
|
|
||||||
|
|
||||||
## 端点说明
|
|
||||||
|
|
||||||
### Usage（请求统计）
|
|
||||||
- GET `/usage` — 获取内存中的请求统计
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"usage": {
|
|
||||||
"total_requests": 24,
|
|
||||||
"success_count": 22,
|
|
||||||
"failure_count": 2,
|
|
||||||
"total_tokens": 13890,
|
|
||||||
"requests_by_day": {
|
|
||||||
"2024-05-20": 12
|
|
||||||
},
|
|
||||||
"requests_by_hour": {
|
|
||||||
"09": 4,
|
|
||||||
"18": 8
|
|
||||||
},
|
|
||||||
"tokens_by_day": {
|
|
||||||
"2024-05-20": 9876
|
|
||||||
},
|
|
||||||
"tokens_by_hour": {
|
|
||||||
"09": 1234,
|
|
||||||
"18": 865
|
|
||||||
},
|
|
||||||
"apis": {
|
|
||||||
"POST /v1/chat/completions": {
|
|
||||||
"total_requests": 12,
|
|
||||||
"total_tokens": 9021,
|
|
||||||
"models": {
|
|
||||||
"gpt-4o-mini": {
|
|
||||||
"total_requests": 8,
|
|
||||||
"total_tokens": 7123,
|
|
||||||
"details": [
|
|
||||||
{
|
|
||||||
"timestamp": "2024-05-20T09:15:04.123456Z",
|
|
||||||
"tokens": {
|
|
||||||
"input_tokens": 523,
|
|
||||||
"output_tokens": 308,
|
|
||||||
"reasoning_tokens": 0,
|
|
||||||
"cached_tokens": 0,
|
|
||||||
"total_tokens": 831
|
|
||||||
}
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"failed_requests": 2
|
|
||||||
}
|
|
||||||
```
|
|
||||||
- 说明：
|
|
||||||
- 仅统计带有 token 使用信息的请求，服务重启后数据会被清空。
|
|
||||||
- 小时维度会将所有日期折叠到 `00`–`23` 的统一小时桶中。
|
|
||||||
- 顶层字段 `failed_requests` 与 `usage.failure_count` 相同，便于轮询。
|
|
||||||
|
|
||||||
### Config
|
|
||||||
- GET `/config` — 获取完整的配置
|
|
||||||
- 请求:
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/config
|
|
||||||
```
|
|
||||||
- 响应:
|
|
||||||
```json
|
|
||||||
{"debug":true,"proxy-url":"","api-keys":["1...5","JS...W"],"quota-exceeded":{"switch-project":true,"switch-preview-model":true},"gemini-api-key":[{"api-key":"AI...01","base-url":"https://generativelanguage.googleapis.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":""},{"api-key":"AI...02","proxy-url":"socks5://proxy.example.com:1080"}],"gl-api-key":["AI...01","AI...02"],"request-log":true,"request-retry":3,"claude-api-key":[{"api-key":"cr...56","base-url":"https://example.com/api","proxy-url":"socks5://proxy.example.com:1080","models":[{"name":"claude-3-5-sonnet-20241022","alias":"claude-sonnet-latest"}]},{"api-key":"cr...e3","base-url":"http://example.com:3000/api","proxy-url":""},{"api-key":"sk-...q2","base-url":"https://example.com","proxy-url":""}],"codex-api-key":[{"api-key":"sk...01","base-url":"https://example/v1","proxy-url":""}],"openai-compatibility":[{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk...01","proxy-url":""}],"models":[{"name":"moonshotai/kimi-k2:free","alias":"kimi-k2"}]},{"name":"iflow","base-url":"https://apis.iflow.cn/v1","api-key-entries":[{"api-key":"sk...7e","proxy-url":"socks5://proxy.example.com:1080"}],"models":[{"name":"deepseek-v3.1","alias":"deepseek-v3.1"},{"name":"glm-4.5","alias":"glm-4.5"},{"name":"kimi-k2","alias":"kimi-k2"}]}]}
|
|
||||||
```
|
|
||||||
- 说明：
|
|
||||||
- 返回中会附带 `gl-api-key`，其内容来自 `gemini-api-key` 的 API Key 列表（仅保留纯字符串视图）。
|
|
||||||
- 若服务尚未加载配置文件，则返回空对象 `{}`。
|
|
||||||
|
|
||||||
### Debug
|
|
||||||
- GET `/debug` — 获取当前 debug 状态
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/debug
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "debug": false }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/debug` — 设置 debug（布尔值）
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":true}' \
|
|
||||||
http://localhost:8317/v0/management/debug
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Config YAML
|
|
||||||
- GET `/config.yaml` — 原样下载持久化的 YAML 配置
|
|
||||||
- 响应头：
|
|
||||||
- `Content-Type: application/yaml; charset=utf-8`
|
|
||||||
- `Cache-Control: no-store`
|
|
||||||
- 响应体：保留注释与格式的原始 YAML 流。
|
|
||||||
- PUT `/config.yaml` — 使用 YAML 文档整体替换配置
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/yaml' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
--data-binary @config.yaml \
|
|
||||||
http://localhost:8317/v0/management/config.yaml
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "ok": true, "changed": ["config"] }
|
|
||||||
```
|
|
||||||
- 说明：
|
|
||||||
- 服务会先加载 YAML 验证其有效性，校验失败返回 `422` 以及 `{ "error": "invalid_config", "message": "..." }`。
|
|
||||||
- 写入失败会返回 `500`，格式 `{ "error": "write_failed", "message": "..." }`。
|
|
||||||
|
|
||||||
### 文件日志开关
|
|
||||||
- GET `/logging-to-file` — 查看是否启用文件日志
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "logging-to-file": true }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/logging-to-file` — 开启或关闭文件日志
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":false}' \
|
|
||||||
http://localhost:8317/v0/management/logging-to-file
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### 日志文件
|
|
||||||
- GET `/logs` — 获取合并后的最新日志行
|
|
||||||
- 查询参数：
|
|
||||||
- `after`（可选）：Unix 时间戳，仅返回该时间之后的日志。
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"lines": ["2024-05-20 12:00:00 info request accepted"],
|
|
||||||
"line-count": 125,
|
|
||||||
"latest-timestamp": 1716206400
|
|
||||||
}
|
|
||||||
```
|
|
||||||
- 说明：
|
|
||||||
- 需要先启用文件日志，否则会以 `400` 返回 `{ "error": "logging to file disabled" }`。
|
|
||||||
- 若当前没有日志文件，返回的 `lines` 为空数组、`line-count` 为 `0`。
|
|
||||||
- DELETE `/logs` — 删除轮换日志并清空主日志
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "success": true, "message": "Logs cleared successfully", "removed": 3 }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Usage 统计开关
|
|
||||||
- GET `/usage-statistics-enabled` — 查看是否启用请求统计
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "usage-statistics-enabled": true }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/usage-statistics-enabled` — 启用或关闭统计
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":true}' \
|
|
||||||
http://localhost:8317/v0/management/usage-statistics-enabled
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### 代理服务器 URL
|
|
||||||
- GET `/proxy-url` — 获取代理 URL 字符串
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/proxy-url
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "proxy-url": "socks5://user:pass@127.0.0.1:1080/" }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/proxy-url` — 设置代理 URL 字符串
|
|
||||||
- 请求（PUT）：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":"socks5://user:pass@127.0.0.1:1080/"}' \
|
|
||||||
http://localhost:8317/v0/management/proxy-url
|
|
||||||
```
|
|
||||||
- 请求（PATCH）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":"http://127.0.0.1:8080"}' \
|
|
||||||
http://localhost:8317/v0/management/proxy-url
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/proxy-url` — 清空代理 URL
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE http://localhost:8317/v0/management/proxy-url
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### 超出配额行为
|
|
||||||
- GET `/quota-exceeded/switch-project`
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-project
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "switch-project": true }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/quota-exceeded/switch-project` — 布尔值
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":false}' \
|
|
||||||
http://localhost:8317/v0/management/quota-exceeded/switch-project
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- GET `/quota-exceeded/switch-preview-model`
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-preview-model
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "switch-preview-model": true }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/quota-exceeded/switch-preview-model` — 布尔值
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":true}' \
|
|
||||||
http://localhost:8317/v0/management/quota-exceeded/switch-preview-model
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### API Keys（代理服务认证）
|
|
||||||
这些接口会更新配置中 `auth.providers` 内置的 `config-api-key` 提供方，旧版顶层 `api-keys` 会自动保持同步。
|
|
||||||
- GET `/api-keys` — 返回完整列表
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/api-keys
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "api-keys": ["k1","k2","k3"] }
|
|
||||||
```
|
|
||||||
- PUT `/api-keys` — 完整改写列表
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '["k1","k2","k3"]' \
|
|
||||||
http://localhost:8317/v0/management/api-keys
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/api-keys` — 修改其中一个（`old/new` 或 `index/value`）
|
|
||||||
- 请求（按 old/new）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"old":"k2","new":"k2b"}' \
|
|
||||||
http://localhost:8317/v0/management/api-keys
|
|
||||||
```
|
|
||||||
- 请求（按 index/value）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"index":0,"value":"k1b"}' \
|
|
||||||
http://localhost:8317/v0/management/api-keys
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/api-keys` — 删除其中一个（`?value=` 或 `?index=`）
|
|
||||||
- 请求（按值删除）：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?value=k1'
|
|
||||||
```
|
|
||||||
- 请求（按索引删除）：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?index=0'
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Gemini API Key
|
|
||||||
- GET `/gemini-api-key`
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/gemini-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"gemini-api-key": [
|
|
||||||
{"api-key":"AIzaSy...01","base-url":"https://generativelanguage.googleapis.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":""},
|
|
||||||
{"api-key":"AIzaSy...02","proxy-url":"socks5://proxy.example.com:1080"}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
- PUT `/gemini-api-key`
|
|
||||||
- 请求（数组形式）：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '[{"api-key":"AIzaSy-1","headers":{"X-Custom-Header":"vendor-value"}},{"api-key":"AIzaSy-2","base-url":"https://custom.example.com"}]' \
|
|
||||||
http://localhost:8317/v0/management/gemini-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/gemini-api-key`
|
|
||||||
- 请求（按索引更新）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"index":0,"value":{"api-key":"AIzaSy-1","base-url":"https://custom.example.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":""}}' \
|
|
||||||
http://localhost:8317/v0/management/gemini-api-key
|
|
||||||
```
|
|
||||||
- 请求（按 api-key 匹配更新）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"match":"AIzaSy-1","value":{"api-key":"AIzaSy-1","headers":{"X-Custom-Header":"custom-value"},"proxy-url":"socks5://proxy.example.com:1080"}}' \
|
|
||||||
http://localhost:8317/v0/management/gemini-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/gemini-api-key`
|
|
||||||
- 请求（按 api-key 删除）：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE \
|
|
||||||
'http://localhost:8317/v0/management/gemini-api-key?api-key=AIzaSy-1'
|
|
||||||
```
|
|
||||||
- 请求（按索引删除）：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE \
|
|
||||||
'http://localhost:8317/v0/management/gemini-api-key?index=0'
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Generative Language API Key（兼容接口）
|
|
||||||
- GET `/generative-language-api-key`
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/generative-language-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "generative-language-api-key": ["AIzaSy...01","AIzaSy...02"] }
|
|
||||||
```
|
|
||||||
- PUT `/generative-language-api-key`
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '["AIzaSy-1","AIzaSy-2"]' \
|
|
||||||
http://localhost:8317/v0/management/generative-language-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/generative-language-api-key`
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"old":"AIzaSy-1","new":"AIzaSy-1b"}' \
|
|
||||||
http://localhost:8317/v0/management/generative-language-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/generative-language-api-key`
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/generative-language-api-key?value=AIzaSy-2'
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- 说明：
|
|
||||||
- 该接口只读写纯字符串列表，实际上会映射到 `gemini-api-key`。
|
|
||||||
|
|
||||||
### Codex API KEY（对象数组）
|
|
||||||
- GET `/codex-api-key` — 列出全部
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/codex-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "codex-api-key": [ { "api-key": "sk-a", "base-url": "", "proxy-url": "" } ] }
|
|
||||||
```
|
|
||||||
- PUT `/codex-api-key` — 完整改写列表
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '[{"api-key":"sk-a","proxy-url":"socks5://proxy.example.com:1080"},{"api-key":"sk-b","base-url":"https://c.example.com","proxy-url":""}]' \
|
|
||||||
http://localhost:8317/v0/management/codex-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/codex-api-key` — 修改其中一个（按 `index` 或 `match`）
|
|
||||||
- 请求（按索引）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com","proxy-url":""}}' \
|
|
||||||
http://localhost:8317/v0/management/codex-api-key
|
|
||||||
```
|
|
||||||
- 请求（按匹配）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":"","proxy-url":"socks5://proxy.example.com:1080"}}' \
|
|
||||||
http://localhost:8317/v0/management/codex-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/codex-api-key` — 删除其中一个（`?api-key=` 或 `?index=`）
|
|
||||||
- 请求（按 api-key）：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?api-key=sk-b2'
|
|
||||||
```
|
|
||||||
- 请求（按索引）：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?index=0'
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### 请求重试次数
|
|
||||||
- GET `/request-retry` — 获取整数
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/request-retry
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "request-retry": 3 }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/request-retry` — 设置整数
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":5}' \
|
|
||||||
http://localhost:8317/v0/management/request-retry
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### 请求日志开关
|
|
||||||
- GET `/request-log` — 获取布尔值
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/request-log
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "request-log": false }
|
|
||||||
```
|
|
||||||
- PUT/PATCH `/request-log` — 设置布尔值
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"value":true}' \
|
|
||||||
http://localhost:8317/v0/management/request-log
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### Claude API KEY（对象数组）
|
|
||||||
- GET `/claude-api-key` — 列出全部
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/claude-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "claude-api-key": [ { "api-key": "sk-a", "base-url": "", "proxy-url": "" } ] }
|
|
||||||
```
|
|
||||||
- PUT `/claude-api-key` — 完整改写列表
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '[{"api-key":"sk-a","proxy-url":"socks5://proxy.example.com:1080"},{"api-key":"sk-b","base-url":"https://c.example.com","proxy-url":""}]' \
|
|
||||||
http://localhost:8317/v0/management/claude-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/claude-api-key` — 修改其中一个（按 `index` 或 `match`）
|
|
||||||
- 请求（按索引）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com","proxy-url":""}}' \
|
|
||||||
http://localhost:8317/v0/management/claude-api-key
|
|
||||||
```
|
|
||||||
- 请求（按匹配）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":"","proxy-url":"socks5://proxy.example.com:1080"}}' \
|
|
||||||
http://localhost:8317/v0/management/claude-api-key
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- DELETE `/claude-api-key` — 删除其中一个（`?api-key=` 或 `?index=`）
|
|
||||||
- 请求（按 api-key）：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?api-key=sk-b2'
|
|
||||||
```
|
|
||||||
- 请求（按索引）：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?index=0'
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### OpenAI 兼容提供商（对象数组）
|
|
||||||
- GET `/openai-compatibility` — 列出全部
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/openai-compatibility
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "openai-compatibility": [ { "name": "openrouter", "base-url": "https://openrouter.ai/api/v1", "api-key-entries": [ { "api-key": "sk", "proxy-url": "" } ], "models": [] } ] }
|
|
||||||
```
|
|
||||||
- PUT `/openai-compatibility` — 完整改写列表
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -X PUT -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '[{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[{"name":"m","alias":"a"}]}]' \
|
|
||||||
http://localhost:8317/v0/management/openai-compatibility
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- PATCH `/openai-compatibility` — 修改其中一个（按 `index` 或 `name`）
|
|
||||||
- 请求（按名称）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"name":"openrouter","value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[]}}' \
|
|
||||||
http://localhost:8317/v0/management/openai-compatibility
|
|
||||||
```
|
|
||||||
- 请求（按索引）：
|
|
||||||
```bash
|
|
||||||
curl -X PATCH -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d '{"index":0,"value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[]}}' \
|
|
||||||
http://localhost:8317/v0/management/openai-compatibility
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- 说明：
|
|
||||||
- 仍可提交遗留的 `api-keys` 字段，但所有密钥会自动迁移到 `api-key-entries` 中，返回结果中的 `api-keys` 会逐步留空。
|
|
||||||
- DELETE `/openai-compatibility` — 删除（`?name=` 或 `?index=`）
|
|
||||||
- 请求（按名称）：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?name=openrouter'
|
|
||||||
```
|
|
||||||
- 请求（按索引）：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?index=0'
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### 认证文件管理
|
|
||||||
|
|
||||||
管理 `auth-dir` 下的 JSON 令牌文件：列出、下载、上传、删除。
|
|
||||||
|
|
||||||
- GET `/auth-files` — 列表
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/auth-files
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "files": [ { "name": "acc1.json", "size": 1234, "modtime": "2025-08-30T12:34:56Z", "type": "google", "email": "user@example.com" } ] }
|
|
||||||
```
|
|
||||||
- 说明：
|
|
||||||
- `modtime` 使用 RFC3339 格式；若文件中包含邮箱字段则一并返回。
|
|
||||||
|
|
||||||
- GET `/auth-files/download?name=<file.json>` — 下载单个文件
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -OJ 'http://localhost:8317/v0/management/auth-files/download?name=acc1.json'
|
|
||||||
```
|
|
||||||
|
|
||||||
- POST `/auth-files` — 上传
|
|
||||||
- 请求（multipart）：
|
|
||||||
```bash
|
|
||||||
curl -X POST -F 'file=@/path/to/acc1.json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
http://localhost:8317/v0/management/auth-files
|
|
||||||
```
|
|
||||||
- 请求（原始 JSON）：
|
|
||||||
```bash
|
|
||||||
curl -X POST -H 'Content-Type: application/json' \
|
|
||||||
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
-d @/path/to/acc1.json \
|
|
||||||
'http://localhost:8317/v0/management/auth-files?name=acc1.json'
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
- 说明：
|
|
||||||
- 需确保核心认证管理器已启用，否则会以 `503` 返回 `{ "error": "core auth manager unavailable" }`。
|
|
||||||
- 上传的文件名必须以 `.json` 结尾。
|
|
||||||
|
|
||||||
- DELETE `/auth-files?name=<file.json>` — 删除单个文件
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/auth-files?name=acc1.json'
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- DELETE `/auth-files?all=true` — 删除 `auth-dir` 下所有 `.json` 文件
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/auth-files?all=true'
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "deleted": 3 }
|
|
||||||
```
|
|
||||||
|
|
||||||
### 登录/授权 URL
|
|
||||||
|
|
||||||
以下端点用于发起各提供商的登录流程，并返回需要在浏览器中打开的 URL。流程完成后，令牌会保存到 `auths/` 目录。
|
|
||||||
|
|
||||||
对于 Anthropic、Codex、Gemini CLI 与 iFlow，可附加 `?is_webui=true` 以便从管理界面复用内置回调转发。
|
|
||||||
|
|
||||||
- GET `/anthropic-auth-url` — 开始 Anthropic（Claude）登录
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
http://localhost:8317/v0/management/anthropic-auth-url
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "url": "https://...", "state": "anth-1716206400" }
|
|
||||||
```
|
|
||||||
- 说明：
|
|
||||||
- 若从 Web UI 触发，可添加 `?is_webui=true` 复用本地回调服务。
|
|
||||||
|
|
||||||
- GET `/codex-auth-url` — 开始 Codex 登录
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
http://localhost:8317/v0/management/codex-auth-url
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "url": "https://...", "state": "codex-1716206400" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- GET `/gemini-cli-auth-url` — 开始 Google（Gemini CLI）登录
|
|
||||||
- 查询参数：
|
|
||||||
- `project_id`（可选）：Google Cloud 项目 ID。
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
'http://localhost:8317/v0/management/gemini-cli-auth-url?project_id=<PROJECT_ID>'
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "url": "https://...", "state": "gem-1716206400" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- GET `/qwen-auth-url` — 开始 Qwen 登录（设备授权流程）
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
http://localhost:8317/v0/management/qwen-auth-url
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "url": "https://...", "state": "gem-1716206400" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- GET `/iflow-auth-url` — 开始 iFlow 登录
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
http://localhost:8317/v0/management/iflow-auth-url
|
|
||||||
```
|
|
||||||
- 响应：
|
|
||||||
```json
|
|
||||||
{ "status": "ok", "url": "https://...", "state": "ifl-1716206400" }
|
|
||||||
```
|
|
||||||
|
|
||||||
- GET `/get-auth-status?state=<state>` — 轮询 OAuth 流程状态
|
|
||||||
- 请求：
|
|
||||||
```bash
|
|
||||||
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
|
|
||||||
'http://localhost:8317/v0/management/get-auth-status?state=<STATE_FROM_AUTH_URL>'
|
|
||||||
```
|
|
||||||
- 响应示例：
|
|
||||||
```json
|
|
||||||
{ "status": "wait" }
|
|
||||||
{ "status": "ok" }
|
|
||||||
{ "status": "error", "error": "Authentication failed" }
|
|
||||||
```
|
|
||||||
|
|
||||||
## 错误响应
|
|
||||||
|
|
||||||
通用错误格式：
|
|
||||||
- 400 Bad Request: `{ "error": "invalid body" }`
|
|
||||||
- 401 Unauthorized: `{ "error": "missing management key" }` 或 `{ "error": "invalid management key" }`
|
|
||||||
- 403 Forbidden: `{ "error": "remote management disabled" }`
|
|
||||||
- 404 Not Found: `{ "error": "item not found" }` 或 `{ "error": "file not found" }`
|
|
||||||
- 422 Unprocessable Entity: `{ "error": "invalid_config", "message": "..." }`
|
|
||||||
- 500 Internal Server Error: `{ "error": "failed to save config: ..." }`
|
|
||||||
- 503 Service Unavailable: `{ "error": "core auth manager unavailable" }`
|
|
||||||
|
|
||||||
## 说明
|
|
||||||
|
|
||||||
- 变更会写回 YAML 配置文件，并由文件监控器热重载配置与客户端。
|
|
||||||
- `allow-remote-management` 与 `remote-management-key` 不能通过 API 修改，需在配置文件中设置。
|
|
||||||
@@ -36,7 +36,7 @@ CLIProxyAPI Guides: [https://help.router-for.me/](https://help.router-for.me/)
|
|||||||
|
|
||||||
## Management API
|
## Management API
|
||||||
|
|
||||||
see [MANAGEMENT_API.md](MANAGEMENT_API.md)
|
see [MANAGEMENT_API.md](https://help.router-for.me/management/api)
|
||||||
|
|
||||||
## SDK Docs
|
## SDK Docs
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -38,7 +38,7 @@ CLIProxyAPI 用户手册： [https://help.router-for.me/](https://help.router-fo
|
|||||||
|
|
||||||
## 管理 API 文档
|
## 管理 API 文档
|
||||||
|
|
||||||
请参见 [MANAGEMENT_API_CN.md](MANAGEMENT_API_CN.md)
|
请参见 [MANAGEMENT_API_CN.md](https://help.router-for.me/cn/management/api)
|
||||||
|
|
||||||
## SDK 文档
|
## SDK 文档
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user