Chat completions
Create a chat completion. ModelRail returns tool calls but does not execute them. For SSE, see Streaming.
POST
/v1/chat/completionsAuth · API key
application/json
Minimal request
curl "https://api.modelrail.dev/v1/chat/completions" \
-H "Authorization: Bearer $MODELRAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "modelrail-chat",
"messages": [{ "role": "user", "content": "Summarize ModelRail in one sentence." }]
}'const response = await fetch("https://api.modelrail.dev/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MODELRAIL_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "modelrail-chat",
messages: [
{ role: "user", content: "Summarize ModelRail in one sentence." },
],
}),
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const completion = await response.json();import os
import requests
response = requests.post(
"https://api.modelrail.dev/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['MODELRAIL_API_KEY']}"},
json={
"model": "modelrail-chat",
"messages": [
{"role": "user", "content": "Summarize ModelRail in one sentence."},
],
},
)
response.raise_for_status()
completion = response.json()Things to note
OpenAI-compatible SDKs work if you set
baseURL to https://api.modelrail.dev/v1.json
{
"id": "chatcmpl_...",
"object": "chat.completion",
"created": 1710000000,
"model": "modelrail-chat",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "...",
"tool_calls": []
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 20,
"total_tokens": 30,
"prompt_tokens_details": { "cached_tokens": 0 }
}
}Headers
| Header | Required | Notes |
|---|---|---|
Authorization | yes | Bearer $MODELRAIL_API_KEY |
Content-Type | JSON POST | application/json |
x-request-id | no | Alphanumeric + ._-, max 128; echoed; use for support |
Common fields
| Field | Required | Notes |
|---|---|---|
model | yes | A ModelRail alias |
messages | yes | Array, length 1–256 |
temperature | no | 0–2 |
max_tokens | no | Mutually exclusive with max_completion_tokens |
stream | no | Default false — see Streaming |
response_format | no | { "type": "text" | "json_object" } |
Things to note
Unknown request fields are rejected.
n must be 1. If neither max-output field is set, the effective default maximum output is 4096 tokens (server caps apply).Messages
Roles: system, developer, user, assistant, tool. Tool messages require tool_call_id.
Content parts
| Part | Notes |
|---|---|
{ "type": "text", "text": "..." } | Text content |
{ "type": "image_url", "image_url": { "url": "https://..." } } | HTTPS only; data: URLs rejected |
Response
| Field | Notes |
|---|---|
finish_reason | stop | length | tool_calls | content_filter (or null) |
usage | May be omitted if upstream did not return it |
model | Always a resolved ModelRail alias |
Field reference
| Field | Required | Type / constraints |
|---|---|---|
model | yes | ModelRail alias |
messages | yes | Array, length 1–256 |
tools | no | Max 64; type function only — Tool calling |
tool_choice | no | "none" | "auto" | "required" | named function |
response_format | no | { "type": "text" | "json_object" } |
temperature | no | 0–2 |
top_p | no | 0–1 |
max_tokens | no | Mutually exclusive with max_completion_tokens |
max_completion_tokens | no | Same constraints as max_tokens |
stop | no | string or string[] (max 4) |
stream | no | boolean, default false |
stream_options | no | { "include_usage": true } only when streaming |
n | no | Only 1 |