API reference

The Kloria API follows the OpenAI and Anthropic formats. Parameters, response shapes and streaming match their respective documentation: this page covers what is specific to Kloria and what you need to know to use it.

Address and authentication

	Value
Base address	https://api.kloria.dev
Endpoint prefix	/v1
Authentication	Authorization: Bearer sk-… on every endpoint
Anthropic-format variant	x-api-key: sk-… on /v1/messages and /v1/models

Only HTTPS is accepted. The key is the one created in the console, under API Keys.

Endpoints

Method	Path	Format	Use
POST	/v1/chat/completions	OpenAI	Chat, all models
POST	/v1/messages	Anthropic	Chat, Claude models
POST	/v1/responses	OpenAI Responses	Used by Codex, GPT models
GET	/v1/models	OpenAI or Anthropic	Models your key can access

Note

Other OpenAI and Anthropic endpoints (images, audio, embeddings, files, batch) aren’t offered for now.

Chat Completions (OpenAI format)

POST /v1/chat/completions accepts the standard OpenAI API body: model, messages, stream, max_tokens or max_completion_tokens, temperature, tools, tool_choice, response_format…

curl https://api.kloria.dev/v1/chat/completions \
  -H "Authorization: Bearer $KLORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 300,
    "messages": [
      {"role": "system", "content": "Answer in one sentence."},
      {"role": "user", "content": "What is a database index for?"}
    ]
  }'

Response (shortened):

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "claude-sonnet-5",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "An index lets the database find rows…" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 29, "completion_tokens": 22, "total_tokens": 51 }
}

Claude models called in this format are converted automatically: you can move from a GPT model to a Claude model by changing only model.

Messages (Anthropic format)

POST /v1/messages accepts the Anthropic Messages API body. max_tokens is required, and the system prompt goes in the system field, not in messages.

curl https://api.kloria.dev/v1/messages \
  -H "x-api-key: $KLORIA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 300,
    "system": "Answer in one sentence.",
    "messages": [{"role": "user", "content": "What is a database index for?"}]
  }'

Response (shortened):

{
  "id": "msg_…",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [{ "type": "text", "text": "An index lets the database find rows…" }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 25, "output_tokens": 22 }
}

The Anthropic format is the right choice for Claude-specific features: content blocks, prompt caching (cache_control), extended thinking. It’s also the format Claude Code uses.

Models

GET /v1/models returns the models your key can access. With the x-api-key and anthropic-version headers, the response follows the Anthropic format; otherwise the OpenAI format:

{
  "object": "list",
  "data": [
    { "id": "claude-sonnet-5", "object": "model", "owned_by": "…" },
    { "id": "gpt-6.1-sol", "object": "model", "owned_by": "…" }
  ]
}

This call doesn’t use credits.

Streaming

Pass "stream": true in the request body. The response arrives as Server-Sent Events (text/event-stream):

• OpenAI format: a series of data: {…} lines carrying deltas, ending with data: [DONE]. To get the token count in the stream, add "stream_options": {"include_usage": true}: the last event then carries usage.
• Anthropic format: the message_start, content_block_delta, message_delta (which carries usage) and message_stop events.

The official SDKs handle these formats for you (see Python SDK and Node.js SDK).

Tracking usage

• Every response includes a usage object with the billed input and output tokens.
• The console shows each request under Usage Logs, with its model, tokens, duration and cost in credits.
• Your balance is shown under Wallet.

Cost calculation is detailed on Models and pricing.

Errors

Errors follow the format of the protocol you called: an error object with a message. The HTTP status gives the category:

Status	Meaning	What to do
400	Invalid request: malformed JSON, missing parameter (max_tokens in Anthropic format), unknown model	Read the message, fix the request
401	Key missing, invalid, disabled or expired	Check the header and the key in the console
403	Balance used up, key quota reached, or model not allowed for this key	Top up, raise the key’s quota or its model limits
429	Too many requests in a short time	Retry after a pause, with increasing delays
500, 502, 503	Temporary model error or unavailability	Retry; if it persists, report it with the time of the request

The most common messages and their causes are on the Troubleshooting page.

Retrying properly

For 429 and 5xx, retry with a delay that doubles each time (1 s, 2 s, 4 s…), and stop after a few attempts. The official SDKs already do this by default for these statuses.