Skip to main content
When you send a request to Flatkey, it authenticates your API key, validates your balance, then forwards the request to the official vendor API for the model you specified. The response flows directly back to your client. Flatkey acts as a transparent proxy — model outputs are never modified or stored.

​
Request lifecycle

  1. Authentication: Flatkey verifies your API key.
  2. Balance check: The estimated cost is reserved from your prepaid balance.
  3. Provider routing: The request is forwarded to the vendor (OpenAI, Anthropic, Google, etc.).
  4. Response passthrough: The vendor’s response is returned unchanged to your client.
  5. Billing settlement: Token counts are confirmed and the exact cost is deducted.

​
Automatic failover

Flatkey monitors the health of upstream provider APIs in real time. If a provider endpoint returns errors or elevated latency, Flatkey can automatically retry on a healthy alternative — without any changes to your code.
Failover operates at the infrastructure level. You do not need to configure anything to benefit from it. Your 99.9% success rate guarantee is backed by this mechanism.

​
Base URL

All requests go to a single base URL:
This single endpoint handles all supported API families:

​
Groups and quotas

From the console you can create Groups to organize API keys and set routing controls:
  • Model access policies: Restrict which models a key or group can call
  • Spend quotas: Set a monthly or per-request spend cap
  • Routing rules: Prefer specific providers or model versions
This is useful for teams that want to limit developers to cheaper models in staging, or enforce a budget for a specific application.

​
Latency considerations

Routing through Flatkey adds minimal overhead — typically under 50ms — compared to calling providers directly. For latency-sensitive applications, choose models with low average latency in the Model Health dashboard.

​
Streaming

Flatkey fully supports streaming for all chat and text generation models:
python
Streaming works for all OpenAI-compatible models. Check individual model documentation for Anthropic or Gemini streaming specifics.

​
Error handling

Flatkey preserves the error format returned by the upstream vendor. If a provider returns a 4xx or 5xx error, you receive it with the same structure as the OpenAI error schema so existing error-handling code continues to work. Common errors and what to do:
Errors from Flatkey itself (authentication, balance) are returned before the request reaches the upstream provider and do not consume any balance.