> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routeway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions

> Generate text, multi-turn conversations, and code using the OpenAI-compatible /v1/chat/completions endpoint.

The `/v1/chat/completions` endpoint is Routeway's primary text generation API. It is 100% compatible with the OpenAI Chat Completions API format, providing access to 200+ models from OpenAI, Anthropic, Google, DeepSeek, xAI, Mistral, and more using a single API key and base URL.

```http theme={null}
POST https://api.routeway.ai/v1/chat/completions
```

***

## Quickstart

> [tab] Python
>
> ```python theme={null}
> import os
> from openai import OpenAI
>
> client = OpenAI(
>     base_url="https://api.routeway.ai/v1",
>     api_key=os.getenv("ROUTEWAY_API_KEY")
> )
>
> response = client.chat.completions.create(
>     model="gpt-4o",
>     messages=[
>         {"role": "system", "content": "You are a concise technical assistant."},
>         {"role": "user", "content": "Explain HTTPS in two sentences."}
>     ],
>     temperature=0.7,
>     max_tokens=150,
> )
>
> print(response.choices[0].message.content)
> ```

> [tab] Node.js
>
> ```javascript theme={null}
> import OpenAI from "openai";
>
> const client = new OpenAI({
>   baseURL: "https://api.routeway.ai/v1",
>   apiKey: process.env.ROUTEWAY_API_KEY,
> });
>
> const response = await client.chat.completions.create({
>   model: "gpt-4o",
>   messages: [
>     { role: "system", content: "You are a concise technical assistant." },
>     { role: "user", content: "Explain HTTPS in two sentences." },
>   ],
>   temperature: 0.7,
>   max_tokens: 150,
> });
>
> console.log(response.choices[0].message.content);
> ```

> [tab] cURL
>
> ```bash theme={null}
> curl https://api.routeway.ai/v1/chat/completions \
>   -H "Authorization: Bearer $ROUTEWAY_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gpt-4o",
>     "messages": [
>       {"role": "system", "content": "You are a concise technical assistant."},
>       {"role": "user", "content": "Explain HTTPS in two sentences."}
>     ],
>     "temperature": 0.7,
>     "max_tokens": 150
>   }'
> ```

***

## Request Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `model` | string | **required** | Model ID to use (e.g. `"gpt-4o"`, `"claude-opus-4-5"`, `"deepseek-v4"`). |
| `messages` | array | **required** | Ordered array of message objects forming the conversation. |
| `max_tokens` | integer | model default | Maximum tokens to generate in the output. |
| `temperature` | number | `1.0` | Sampling temperature (`0` = deterministic, `2` = highly random). |
| `top_p` | number | `1.0` | Nucleus sampling probability mass. Use either `temperature` or `top_p`. |
| `stream` | boolean | `false` | When `true`, streams token chunks using Server-Sent Events (SSE). |
| `tools` | array | — | List of functions the model can call. |
| `tool_choice` | string / object | `"auto"` | Controls tool calling behavior (`"auto"`, `"none"`, `"required"`, or specific function). |
| `response_format` | object | — | Forces structured JSON output (`{"type": "json_object"}` or `{"type": "json_schema", ...}`). |
| `reasoning_effort` | string | — | Reasoning effort level (`"low"`, `"medium"`, `"high"`) for reasoning models. |

***

## Messages & Roles

Every request is structured around an ordered `messages` array:

### Roles

* **`system`**: Sets global rules, tone, and constraints for the model. Put this first.
* **`user`**: The end-user prompt or instruction. Can be a string or a rich content array containing images and PDFs.
* **`assistant`**: The model's reply from prior turns.

### Multi-turn Conversations

Language models are stateless. To maintain conversation context, append each assistant response and subsequent user message to the array:

```python theme={null}
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the boiling point of water?"},
    {"role": "assistant", "content": "Water boils at 100°C (212°F) at standard atmospheric pressure."},
    {"role": "user", "content": "What about at high altitude?"}
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages
)
```

***

## Response Object

A standard successful completion returns:

```json theme={null}
{
  "id": "chatcmpl-abc123xyz",
  "object": "chat.completion",
  "created": 1749052800,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "At higher altitudes, atmospheric pressure is lower, so water boils at a lower temperature."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 24,
    "total_tokens": 72
  }
}
```

### `finish_reason` Values

| Value | Meaning | Recommended Action |
| - | - | - |
| `"stop"` | Generation completed naturally. | Process response. |
| `"length"` | Generation hit `max_tokens` or context limit. | Increase `max_tokens` or summarize previous turns. |
| `"tool_calls"` | The model is requesting a function execution. | Execute requested function and submit result. |
| `"content_filter"` | Response blocked by safety policy. | Adjust prompt content. |

***

## Tokens & Context Windows

Every request is measured in **tokens** (roughly 4 characters of English text):

* **`prompt_tokens`**: Tokens in your `messages` array, system instructions, and schemas.
* **`completion_tokens`**: Tokens generated by the model.
* **Context Window**: Maximum sum of prompt + completion tokens allowed in a single request (e.g. 128k for GPT-4o, 200k for Claude 3.5, 1M+ for Gemini).

### Managing Context Limits

When conversations grow long:

1. **Sliding Window**: Retain the `system` message and only the last $N$ turns.
2. **Conversation Summarization**: Periodically summarize older messages into an assistant summary block.
3. **Prompt Caching**: Take advantage of [Prompt Caching](https://docs.routeway.ai/features/prompt-caching.md) to dramatically cut cost and latency for repetitive system prompts and long reference material.

***

## Advanced Capabilities

Explore specific features built on Chat Completions:

> [card] [Server Tools (@online, @flux)](https://docs.routeway.ai/features/server-tools.md)
>
> Search the web or generate images directly in chat by appending `@online` or `@flux-2-turbo` to model names.

> [card] [Streaming](https://docs.routeway.ai/features/streaming.md)
>
> Receive tokens in real time using Server-Sent Events (SSE).

> [card] [Tool Calling](https://docs.routeway.ai/features/tool-calling.md)
>
> Provide custom functions and schemas for models to execute.

> [card] [Structured Outputs](https://docs.routeway.ai/features/structured-outputs.md)
>
> Guarantee response conformity with JSON Schema validation.

> [card] [Reasoning Models](https://docs.routeway.ai/features/reasoning.md)
>
> Configure thinking budgets and effort levels for DeepSeek R1, OpenAI o-series, and Claude reasoning.

> [card] [Multimodal Inputs](https://docs.routeway.ai/features/multimodal.md)
>
> Pass images, charts, and PDF documents directly in message arrays.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.