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

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".

array

required

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

integer

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

number

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

boolean

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

number

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

string | array

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

array

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

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.

array

Array of generated completion choices.

Show choice properties

string

The generated text.

string

Always "assistant" for generated messages.

string

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

object

Token counts for billing.

Show usage properties

integer

Input token count.

integer

Output token count.

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)

Overview

Endpoints

Chat Completions — POST /v1/chat/completions

Endpoint

Request

Headers

Body parameters

Example request

Response

Response fields

Streaming

​Endpoint

​Request

​Headers

​Body parameters

​Example request

​Response

​Response fields

​Streaming

Endpoint

Request

Headers

Body parameters

Example request

Response

Response fields

Streaming