Developer guide
Authenticate with an API key
The header containing the API key and the base URL to configure in the SDK
This page covers how to authenticate with an API key to the CLEVI gateway.
Both the OpenAI-compatible and Anthropic-compatible endpoints use a single key for authentication,
but the accepted header containing the key and the base URL to configure in the SDK differ by specification.
Authentication headers
Both compatible specifications use a single API key for authentication. Keys are issued on the API Keys page in the console, where you can also revoke them and manage their usage scope.
| Header | OpenAI-compatible | Anthropic-compatible |
|---|---|---|
| X-API-Key: <key> | Accepted | Accepted |
| Authorization: Bearer <key> | Accepted | Accepted |
| Authorization: <key> (without Bearer) | Rejected | Accepted |
Header names are case-insensitive. x-api-key sent by the Anthropic SDK also works as is.
base URL
Your existing SDK will continue to work if you only change the base URL to one of the addresses below. The two addresses differ in whether they include /v1.
| Specification | base URL | Path rules |
|---|---|---|
| OpenAI-compatible | https://platform.clevi.net/api/v2/aiservice/openai/v1 | Include up to /v1 in the base URL. |
| Anthropic-compatible | https://platform.clevi.net/api/v2/aiservice/anthropic | The Anthropic SDK adds /v1 to the path automatically, so the base URL ends before /v1. |
Verify authentication
You can immediately verify whether authentication works by entering the key and base URL and retrieving the model list. The three examples below make the same request using curl, the OpenAI SDK, and the Anthropic SDK.
curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
-H "X-API-Key: sk-..."
curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
-H "Authorization: Bearer sk-..." \
-H "anthropic-version: 2023-06-01"from openai import OpenAI
client = OpenAI(
api_key="sk-...",
base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)
for model in client.models.list():
print(model.id)from anthropic import Anthropic
client = Anthropic(
api_key="sk-...",
base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)
for model in client.models.list(limit=20).data:
print(model.id)Replace sk-... with the key issued on the API Keys page.
- A 200 response means authentication was successful. data contains the list of models that can be called with this key.
- If the response is 401, check the steps in the Authentication failure section below.
Headers used together
All are optional. To track issues, it is recommended to include X-Request-Id.
| Header | Purpose | If omitted |
|---|---|---|
| X-Request-Id | Identifier for tracking requests. It is returned as the request-id header in Anthropic-compatible responses. | Issued by the server. |
| X-Region-Code | Request region | global. |
| X-Product-Sku (also available as the product_sku query parameter) | Directly specifies the Product SKU to use for billing. The header takes precedence over the query parameter and is primarily used for voice routes. | Required for voice routes. For audio/speech and audio/transcriptions, select the Product using model in the body. |
| anthropic-version / anthropic-beta | Passed through unchanged on Anthropic-compatible routes. | The version is 2023-06-01. |
Authentication failure
If you send a missing, expired, or revoked key, the response is 401. If you make a call without a key on an OpenAI-compatible route, the response body below is returned, and error.type on an Anthropic-compatible route is authentication_error.
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}- Check the key status on the API key page. If the key is expired or revoked, issue a new one.
- Check whether the header name is X-API-Key or Authorization.
- If you use Authorization on an OpenAI-compatible route, check the Bearer prefix.