API Reference

Base-URL: https://cleverouter.eu/v1. Authentifizierung über Authorization: Bearer <key>.

POST `/v1/chat/completions`

Erstellt eine Chat-Completion, optional gestreamt. Wire-kompatibel zur OpenAI-API.

Headers

Header	Required	Beschreibung
`Authorization: Bearer <key>`	yes	API-Key
`Content-Type: application/json`	yes	—
`X-CleverRouter-Strategy`	no	`default` `cheapest` `fastest` `best`
`X-CleverRouter-Provider`	no	Pinning, z.B. `scaleway`
`X-CleverRouter-Provider-Prefer`	no	Soft-Preference mit Failover
`X-CleverRouter-Max-Hops`	no	`0`–`5`, default `2`
`X-Idempotency-Key`	no	Schutz gegen Doppel-Calls bei Failover

Request-Body

Feld	Typ	Default	Beschreibung
`model`	string	—	`<family>/<model>`
`messages`	array	—	Chat-History
`stream`	boolean	`false`	SSE aktivieren
`temperature`	number	`1.0`	0–2
`max_tokens`	integer	—	Hard-Limit für Completion
`tools`	array	—	siehe Tool Use
`tool_choice`	string \| object	`auto`	—
`response_format`	object	—	`{ type: 'json_object' }` oder JSON-Schema
`reasoning_effort`	string	—	`low` `medium` `high`
`seed`	integer	—	reproduzierbar, soweit Provider unterstützt

Beispiel

curl https://cleverouter.eu/v1/chat/completions \
  -H "Authorization: Bearer $CLEVERROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-CleverRouter-Strategy: cheapest" \
  -d '{
    "model": "mistral/mistral-small-3.2",
    "messages": [{ "role": "user", "content": "Hallo." }]
  }'

Response

{
  "id": "chatcmpl-9f8c…",
  "object": "chat.completion",
  "created": 1747000000,
  "model": "mistral/mistral-small-3.2",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": { "role": "assistant", "content": "Hallo, wie kann ich helfen?" }
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 7, "total_tokens": 19 }
}

Response-Header verraten den gewählten Provider:

X-CleverRouter-Provider: scaleway
X-CleverRouter-Region: par1
X-CleverRouter-Strategy: cheapest
X-CleverRouter-Routing-Hops: 0

Error-Codes

HTTP	`error.code`	Bedeutung
400	`invalid_request`	Body-Schema falsch
400	`model_not_found`	Modell-ID existiert nicht
400	`provider_unsupported`	Pinning auf Provider ohne Hosting
401	`invalid_api_key`	Auth fehlt oder abgelaufen
402	`quota_exceeded`	Workspace-Budget erschöpft
429	`rate_limited`	Rate-Limit, `Retry-After` beachten
502	`upstream_unavailable`	Alle Provider failed
504	`upstream_timeout`	Read-Timeout, Idempotency-Key bei Retry

GET `/v1/models`

Gibt alle für deinen Workspace freigeschalteten Modelle zurück — mit Provider-Routes, Capability-Flags und Live-Preisen.

curl https://cleverouter.eu/v1/models \
  -H "Authorization: Bearer $CLEVERROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "mistral/mistral-small-3.2",
      "owned_by": "mistral",
      "providers": ["mistral", "scaleway"],
      "regions": ["par1"],
      "capabilities": ["streaming", "tools", "json"],
      "context_window": 128000,
      "pricing": { "prompt_per_1m": 0.1, "completion_per_1m": 0.3, "currency": "EUR" }
    }
  ]
}

Query-Filter: ?family=mistral, ?capability=vision, ?provider=scaleway. Detail-Endpoint: GET /v1/models/{model_id} (Slash URL-encoden: mistral%2Fmistral-large-2).

POST `/v1/embeddings`

Coming Soon — Phase 5

Embeddings sind aktuell in Private Beta. Zugriff anfragen unter /app/early-access.

OpenAI-kompatibler Embeddings-Endpoint. Unterstützte Beta-Modelle: cohere/embed-multilingual-v3 (OVH), mistral/mistral-embed, voyage/voyage-3-large:eu.

curl https://cleverouter.eu/v1/embeddings \
  -H "Authorization: Bearer $CLEVERROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/embed-multilingual-v3",
    "input": ["Hallo aus der EU."],
    "encoding_format": "float"
  }'

Beta-Limits: 500 Requests/Minute pro Workspace, max. 200k Tokens/Minute.

On this page