Every interaction with Routeway follows the same request/response cycle. Understanding the shape of these objects makes it easier to integrate the API, handle edge cases, and debug issues.
Request Object
A minimal chat completion request looks like this:
{
"model": "gpt-4o-mini",
"messages": [
{ "role": "user", "content": "What is 2 + 2?" }
]
}
Common Parameters
| Parameter | Type | Default | Description |
|---|
model | string | required | Model ID to use (e.g. "gpt-4o", "claude-opus-4-5") |
messages | array | required | Ordered list of conversation turns |
max_tokens | integer | model default | Maximum output tokens to generate |
temperature | number | 1.0 | Sampling temperature (0 = deterministic, 2 = very random) |
top_p | number | 1.0 | Nucleus sampling threshold |
stream | boolean | false | Stream tokens as SSE chunks |
tools | array | — | Function schemas the model may call |
tool_choice | string / object | "auto" | How the model selects tools |
response_format | object | — | Force json_object or json_schema output |
reasoning_effort | string | — | "low" / "medium" / "high" for OpenAI reasoning models |
temperature and top_p both control randomness. Use one or the other — not both. For deterministic tasks like data extraction, set temperature: 0. For creative tasks, try values between 0.7 and 1.2.
Full Request Example
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 assistant."},
{"role": "user", "content": "Name the planets in our solar system."}
],
max_tokens=150,
temperature=0.3,
)
print(response.choices[0].message.content)
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 assistant." },
{ role: "user", content: "Name the planets in our solar system." },
],
max_tokens: 150,
temperature: 0.3,
});
console.log(response.choices[0].message.content);
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 assistant."},
{"role": "user", "content": "Name the planets in our solar system."}
],
"max_tokens": 150,
"temperature": 0.3
}'
Response Object
A successful response looks like this:
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1749052800,
"model": "gpt-4o-2024-11-20",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The eight planets are Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 22,
"total_tokens": 50
}
}
Key Fields
| Field | Description |
|---|
id | Unique identifier for this completion |
model | The exact model snapshot that was used |
choices | Array of generated responses (usually one) |
choices[0].message.content | The model’s text reply |
choices[0].finish_reason | Why the model stopped generating |
usage | Token counts for billing |
finish_reason Values
| Value | Meaning |
|---|
"stop" | Model finished naturally |
"length" | Hit max_tokens limit — response may be truncated |
"tool_calls" | Model wants to call a function |
"content_filter" | Response blocked by a content policy |
"null" | Stream is still in progress (streaming only) |
Always check finish_reason. A value of "length" means the response was cut off. Handle it by either increasing max_tokens or detecting and requesting a continuation.
Accessing the Response Text
The model’s reply lives at choices[0].message.content:
text = response.choices[0].message.content
n > 1, multiple completions are returned and you index into choices[0], choices[1], etc.
When the model calls a tool instead of replying with text, content may be null and tool_calls will be populated:
message = response.choices[0].message
if message.tool_calls:
# model wants to call a function
for tc in message.tool_calls:
print(tc.function.name, tc.function.arguments)
else:
# normal text response
print(message.content)
Error Responses
When something goes wrong, Routeway returns a standard error object:
{
"error": {
"message": "Invalid model: 'gpt-999'.",
"type": "invalid_request_error",
"code": "model_not_found"
}
}
| HTTP status | Type | Common causes |
|---|
400 | invalid_request_error | Bad parameters, context too long, invalid model ID |
401 | authentication_error | Missing or invalid API key |
429 | rate_limit_error | Too many requests or insufficient balance |
500 | server_error | Upstream provider error |
Every request must include:
Authorization: Bearer YOUR_ROUTEWAY_API_KEY
Content-Type: application/json
x-request-id header you can use when contacting support about a specific call.