Reference
API Reference
One gateway, compatible with both OpenAI and Anthropic — just change the base URL and keep your code.
Base URLs
OpenAI clients append paths to {base}/v1. The Anthropic base has no /v1 — the SDK adds /v1/messages automatically.
Authentication
Send the gateway key in either header. If you send both, Authorization wins.
Authorization: Bearer $LLMFLUX_API_KEY
x-api-key: $LLMFLUX_API_KEYNo key → 401 missing_api_key. Invalid/expired/revoked key → 401 invalid_api_key. Out of credit → 402 quota_exhausted.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /v1 | Health check and endpoint discovery |
| GET | /v1/models | List all enabled catalogue models |
| GET | /v1/usage | Remaining quota and credit |
| POST | /v1/chat/completions | Chat completions (OpenAI format) |
| POST | /v1/responses | Responses (OpenAI format) |
| POST | /v1/messages | Messages (Anthropic format) |
| POST | /v1/images/generations | Image generation (OpenAI format) |
Models
The catalogue is administrator-controlled and changes with upstream synchronization. Call GET /v1/models with an active key for all enabled models. Copy an exact returned ID or its canonical root when present; metadata is descriptive, not a guarantee of endpoint or tool support.
auto falls back to an enabled ID ending in /auto, otherwise the first enabled catalogue row. Dots are not converted to dashes. Unknown or disabled models return 404 invalid_model. See the Models reference for details.Requests
Replace model placeholders with compatible IDs from the live catalogue. Detailed references: Chat completions, Responses, Messages, Streaming and Errors.
Chat completions · OpenAI
curl https://api.llmflux.dev/v1/chat/completions \
-H "Authorization: Bearer $LLMFLUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"messages": [{ "role": "user", "content": "Hello" }]
}'Messages · Anthropic
curl https://api.llmflux.dev/v1/messages \
-H "x-api-key: $LLMFLUX_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"max_tokens": 1024,
"messages": [{ "role": "user", "content": "Hello" }]
}'Image generation · OpenAI
curl https://api.llmflux.dev/v1/images/generations \
-H "Authorization: Bearer $LLMFLUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_IMAGE_MODEL_ID",
"prompt": "a glowing node graph, neon yellow",
"size": "1024x1024"
}'Streaming
Set "stream": true — the gateway sends text/event-stream with no buffering (no-transform). If an error occurs after the stream has started (HTTP 200 already sent) it arrives as a frame:
event: error
data: {"error":{"message":"...","type":"api_error","code":"upstream_error"}}Usage
GET /v1/usage returns account-wide usage and balance for the key's owner:
{
"label": "gateway-key",
"tokens_total": 1000000,
"tokens_used": 12480,
"tokens_remaining": 987520,
"credits_remaining": 0.1487,
"tokens_per_credit": 6666667,
"status": "active"
}Errors
Every error uses one envelope shape. The code also comes back as the header x-gateway-error-code. Provider error text is never leaked.
The backend defines context and policy codes, but generic upstream HTTP 400 currently maps to bad_request, not a provider-text-specific diagnosis. See the Errors reference for actual status mapping.
{
"error": {
"message": "Missing API key. Add header: Authorization: Bearer <your-key>",
"type": "authentication_error",
"code": "missing_api_key"
}
}| Code | HTTP | Type | Meaning |
|---|---|---|---|
missing_api_key | 401 | authentication_error | No API key in the header |
invalid_api_key | 401 | authentication_error | Key invalid / expired / revoked |
permission_denied | 403 | permission_error | Key not allowed for this model |
quota_exhausted | 402 | invalid_request_error | Out of credit |
rate_limit_exceeded | 429 | rate_limit_error | Too many requests — over the rate limit |
context_length_exceeded | 400 | invalid_request_error | Context longer than allowed |
content_policy_violation | 400 | invalid_request_error | Content violates policy |
invalid_model | 404 | invalid_request_error | Model doesn't exist or key not allowed |
payload_too_large | 413 | invalid_request_error | Request body too large (default 25MB) |
invalid_json | 400 | invalid_request_error | Body is not valid JSON |
service_unavailable | 503 | api_error | Service busy — please try again |
gateway_timeout | 504 | api_error | Timed out reaching the provider |
upstream_error | 502 | api_error | The provider returned an error |
internal_error | 500 | api_error | Unexpected gateway error |