Core Concepts
Routes, API keys, capabilities, and how LatentKit resolves provider execution.
API keys
Each API key belongs to one workspace and one key identity. The key's assigned published route determines provider/model selection for every /v1/* request.
Routes and policies
Build routes (routing policies) in the console from ordered provider/model attempts, capability filters, budgets, and optional request overrides. Publishing a route makes it available for assignment to API keys.
Your application never references route IDs directly — assignment happens in the console.
Purposes
The chain is API key → app → published route. A purpose intercepts the last step: when a request names a purpose your workspace declared for that app, the purpose's route runs instead of the app's assigned one.
That is the whole mechanism. The caller supplies a label, never a model or a route ID,
and a label nobody configured falls back to the app's assigned route rather than failing.
Purpose is what lets one API key send bulk classification to a cheap route and
occasional research to your strongest reasoning route.
Labels are declared per workspace, so read yours from /v1/me rather than hardcoding one
you saw in an example.
Capabilities
Endpoints map to capabilities such as text, embeddings, image_generation, and vision. The route's model catalog and provider support must include an eligible model for the requested capability.
Common public endpoints:
| Endpoint | Capability |
|---|---|
POST /v1/chat | Text / chat |
POST /v1/complete | Text completion |
POST /v1/embeddings | Embeddings |
POST /v1/image | Image generation |
POST /v1/vision | Vision |
POST /v1/transcription | Audio input / speech-to-text |
POST /v1/translation | Audio input / translation |
POST /v1/speech | Audio output / text-to-speech |
POST /v1/video | Video generation |
POST /v1/queue | Async wrapper around any endpoint above |
Some capabilities are added automatically from request content: image parts in chat messages require vision, tools requires function_calling, and "modalities": ["audio"] requires audio_output. See Models & providers for the full capability matrix.
Request lifecycle
Every /v1/* request follows the same path:
- Authenticate — LatentKit validates the API key.
- Load the route — the published route assigned to the key is selected.
- Apply the purpose — if the request names a purpose configured for this app, that purpose's route replaces the assigned one. An unknown purpose keeps the assigned route.
- Find eligible models — models are filtered by capability, availability, and plan access.
- Run with fallback — eligible route entries are attempted according to the configured strategy.
- Return one response — the winning provider response is normalized into the public response contract.
Failover
When the first route attempt fails with a retryable provider error, LatentKit tries the next eligible route in the published policy. The client still receives one response.
Response profiles
response_profile (fast, balanced, thinking) lets applications request a speed/depth tradeoff when the assigned route allows overrides. If overrides are disabled, the route default applies.
Response profile and purpose are orthogonal: purpose picks the route, profile picks among that route's entries.
Credits and BYOK
- Platform Access routes consume LatentKit credits (or trial allowance on Free plans).
- BYOK routes use your provider credentials; LatentKit does not bill model usage for those requests, and adds no margin — you pay your provider its own rate. Reported
cost_usdis an estimate of the provider charge, not a LatentKit charge.
Playground and console testing
Use AI Router or Playground in the console to validate key, route, provider, and billing state before debugging application code. Public docs show the contract; console tools know your workspace state.