Chat Completions — POST /v1/chat/completions

The /v1/chat/completions endpoint generates a text completion based on a list of messages. It is the primary endpoint for chat, instruction-following, and text generation tasks. The request format is identical to the OpenAI Chat Completions API, so any OpenAI-compatible SDK works without modification.

Endpoint

POST https://router.flatkey.ai/v1/chat/completions

Request

Headers

Header	Value
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

Body parameters

model

string

required

The model ID to use. See the Model Directory for all valid values. Example: "gpt-4o", "claude-sonnet-4-5", "gemini-2.5-flash".

messages

array

required

An array of message objects representing the conversation. Each object must have role ("system", "user", or "assistant") and content (string).

max_tokens

integer

Maximum number of tokens to generate. Defaults vary by model.

temperature

number

Sampling temperature between 0 and 2. Higher values produce more random output. Default: 1.

stream

boolean

If true, the response is returned as a stream of server-sent events (SSE). Default: false.

top_p

number

Nucleus sampling — only tokens in the top top_p probability mass are considered. Default: 1.

stop

string | array

One or more sequences where the model stops generating. Can be a string or an array of strings.

tools

array

A list of tool definitions for function calling. Each tool must have type: "function" and a function object with name, description, and parameters.

tool_choice

string | object

Controls tool selection: "none", "auto", "required", or a specific tool {"type": "function", "function": {"name": "..."}}.

Example request

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="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the speed of light?"},
    ],
    max_tokens=256,
    temperature=0.7,
)

print(response.choices[0].message.content)

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the speed of light?"}
    ],
    "max_tokens": 256
  }'

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The speed of light in a vacuum is approximately 299,792,458 meters per second."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 22,
    "total_tokens": 50
  }
}

Response fields

string

Unique identifier for the completion.

choices

array

Array of generated completion choices.

Show choice properties

message.content

string

The generated text.

message.role

string

Always "assistant" for generated messages.

finish_reason

string

Why generation stopped: "stop" (natural end), "length" (max_tokens reached), "tool_calls" (tool invoked).

usage

object

Token counts for billing.

Show usage properties

prompt_tokens

integer

Input token count.

completion_tokens

integer

Output token count.

total_tokens

integer

Sum of prompt and completion tokens.

Streaming

Set stream: true to receive a stream of SSE chunks. Each chunk has the same structure but with partial delta content instead of a full message:

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

​Endpoint

​Request

​Headers

​Body parameters

​Example request

​Response

​Response fields

​Streaming

Endpoint

Request

Headers

Body parameters

Example request

Response

Response fields

Streaming