ModelRail

Docs
Dashboard

Chat completions

Create a chat completion. ModelRail returns tool calls but does not execute them. For SSE, see Streaming.

POST/v1/chat/completions

Auth · 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." }]
  }'

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

HeaderRequiredNotes
AuthorizationyesBearer $MODELRAIL_API_KEY
Content-TypeJSON POSTapplication/json
x-request-idnoAlphanumeric + ._-, max 128; echoed; use for support

Common fields

FieldRequiredNotes
modelyesA ModelRail alias
messagesyesArray, length 1–256
temperatureno0–2
max_tokensnoMutually exclusive with max_completion_tokens
streamnoDefault false — see Streaming
response_formatno{ "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

PartNotes
{ "type": "text", "text": "..." }Text content
{ "type": "image_url", "image_url": { "url": "https://..." } }HTTPS only; data: URLs rejected

Response

FieldNotes
finish_reasonstop | length | tool_calls | content_filter (or null)
usageMay be omitted if upstream did not return it
modelAlways a resolved ModelRail alias

Field reference

FieldRequiredType / constraints
modelyesModelRail alias
messagesyesArray, length 1–256
toolsnoMax 64; type function only — Tool calling
tool_choiceno"none" | "auto" | "required" | named function
response_formatno{ "type": "text" | "json_object" }
temperatureno0–2
top_pno0–1
max_tokensnoMutually exclusive with max_completion_tokens
max_completion_tokensnoSame constraints as max_tokens
stopnostring or string[] (max 4)
streamnoboolean, default false
stream_optionsno{ "include_usage": true } only when streaming
nnoOnly 1