> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flatkey.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate text with Flatkey
> Call any chat model through one endpoint. Covers model choice, streaming, tool calling, structured outputs, and reading token usage.
Base URL: `https://router.flatkey.ai`
Text generation runs through `POST /v1/chat/completions`, which matches the OpenAI Chat Completions API exactly. Any OpenAI-compatible client works after you change the base URL.
Keep your existing request code and point `base_url` at `https://router.flatkey.ai/v1`.
Switch models by changing the `model` field. Nothing else changes.
## Make your first call
```python Python theme={"dark"}
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url="https://router.flatkey.ai/v1",
)
response = client.chat.completions.create(
model="claude-sonnet-5",
messages=[{"role": "user", "content": "Explain vector databases in two sentences."}],
)
print(response.choices[0].message.content)
```
```typescript TypeScript theme={"dark"}
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: "claude-sonnet-5",
messages: [{ role: "user", content: "Explain vector databases in two sentences." }],
});
console.log(response.choices[0].message.content);
```
```bash cURL theme={"dark"}
curl --fail-with-body -sS https://router.flatkey.ai/v1/chat/completions \
-H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"messages": [
{ "role": "user", "content": "Explain vector databases in two sentences." }
]
}'
```
## Choose a model
List everything your account can reach and keep the text models:
```bash theme={"dark"}
curl --fail-with-body -sS https://router.flatkey.ai/v1/models \
-H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
| jq '.data[] | select(.type == "text") | .id'
```
Browse the same list with pricing, context length, and latency on the [model directory](https://flatkey.ai/models).
A practical starting point:
| Need | Try |
| ------------------------------------ | -------------------------------------------- |
| Everyday coding and reasoning | `claude-sonnet-5`, `gpt-5.6-sol` |
| Long documents or whole repositories | `deepseek-v4-pro`, `kimi-k3` |
| High volume at low cost | `deepseek-v4-flash`, `gemini-2.5-flash-lite` |
| Agentic coding | `glm-5.3`, `claude-opus-5` |
## Stream the response
Set `stream: true` to receive tokens as they are produced:
```python theme={"dark"}
stream = client.chat.completions.create(
model="gemini-2.5-flash",
messages=[{"role": "user", "content": "Write a haiku about routing."}],
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="", flush=True)
```
Each chunk carries a partial `delta` instead of a complete message.
## Call your own functions
Pass tool definitions and the model decides when to invoke them:
```python theme={"dark"}
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
response = client.chat.completions.create(
model="claude-sonnet-5",
messages=[{"role": "user", "content": "What is the weather in Paris?"}],
tools=tools,
)
print(response.choices[0].message.tool_calls)
```
To finish the loop, append the assistant message, then one message per tool result keyed by `tool_call_id`, and send the whole thread back.
When a tool fires, `finish_reason` is `tool_calls`, not `stop`. Code that only checks for `stop` will drop the call silently.
Tool calling is a capability of the model, not of Flatkey. The GPT, Claude, Gemini, Qwen, DeepSeek, and GLM families support it. Image, video, and speech models ignore a `tools` array.
## Force a JSON shape
Use `response_format` when you need to parse the answer:
```python theme={"dark"}
response = client.chat.completions.create(
model="gpt-5.6-sol",
messages=[{"role": "user", "content": "Extract the city and country."}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "location",
"strict": True,
"schema": {
"type": "object",
"properties": {"city": {"type": "string"}, "country": {"type": "string"}},
"required": ["city", "country"],
"additionalProperties": False,
},
},
},
)
```
`{"type": "json_object"}` also works when you only need valid JSON without a fixed schema.
## Read token usage
Every response carries the counts you are billed on:
```json theme={"dark"}
"usage": {
"prompt_tokens": 28,
"completion_tokens": 22,
"total_tokens": 50
}
```
Different model families tokenize differently, so the same text costs a different number of tokens on different models. Use `usage` rather than estimating from character counts. Per-request cost also appears in [Usage logs](/dashboard/usage).
## Troubleshooting
**`No available channel for model ...`**
That model is not routable right now. Pick another id from `/v1/models`. Retrying the same model does not clear this.
**The response stops mid-sentence**
`finish_reason` is `length`. Raise `max_tokens`.
**Tool calls never fire**
Confirm the model supports tools, and check that `tool_choice` is not set to `none`.
## Next steps
Every parameter and response field.
Drop Flatkey into an existing OpenAI project.