Chat Completions

POST /api/v1/chat/completions

The chat completions endpoint is OpenAI-compatible. Send chat messages and receive model responses with streaming support. All requests are automatically processed through your Xilos routing rules, guardrails, and orchestration pipeline.

Request Body

Parameter	Type	Required	Description
`model`	string	No	Model ID or `"xilos"` for smart routing. Defaults to `"xilos"`.
`messages`	array	Yes	Array of message objects with `role` and `content`.
`temperature`	number	No	Sampling temperature (0-2). Defaults to rule or org config.
`max_tokens`	number	No	Maximum tokens in the response.
`stream`	boolean	No	If true, returns a stream of server-sent events. Default: `false`.
`tools`	array	No	Array of tool definitions for function calling.
`tool_choice`	string	No	Tool selection strategy (`"auto"`, `"none"`, or specific tool).

Message Object

{
  role: "system" | "user" | "assistant" | "tool",
  content: string | Array<ContentPart>  // ContentPart supports text and image_url
}

Info: Xilos supports multi-modal content. Set the message content to an array of parts (text + image_url) to send images. Only models with supports_images: true will accept image content.

Examples

cURL

    curl https://api.xilos.ai/api/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_XILOS_API_KEY" \
      -d '{
        "model": "xilos",
        "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "What is the capital of France?"}
        ]
      }'

Python

    from openai import OpenAI
 
    client = OpenAI(
        api_key="YOUR_XILOS_API_KEY",
        base_url="https://api.xilos.ai/api/v1"
    )
 
    response = client.chat.completions.create(
        model="xilos",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "What is the capital of France?"}
        ]
    )
 
    print(response.choices[0].message.content)

JavaScript

    import OpenAI from "openai";
 
    const client = new OpenAI({
      apiKey: "YOUR_XILOS_API_KEY",
      baseURL: "https://api.xilos.ai/api/v1",
    });
 
    const response = await client.chat.completions.create({
      model: "xilos",
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "What is the capital of France?" },
      ],
    });
 
    console.log(response.choices[0].message.content);

Streaming

Set stream: true to receive a stream of server-sent events (SSE):

stream = client.chat.completions.create(
    model="xilos",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True
)
 
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Response Format

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "claude-sonnet-4-20250514",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

How Xilos Processes the Request

When you send a chat completion request to Xilos:

Authentication — The API key is validated.
Consolidation — Messages are consolidated into a query.
Guardrails — PII detection, HAP, and jailbreak checks run locally.
Restrictions — Restriction rules are evaluated (block, mask, or flag).
Cache Check — Semantic cache is checked for a matching response.
Routing — Smart Routing or routing rules select the target model.
Compression — Context compression reduces token count (if enabled).
LLM Call — The query is sent to the selected LLM provider.
Response — The response is returned, logged, and cached.
Webhooks — Event-driven webhooks fire (if configured).

Error Codes

Status	Description
400	Bad request — invalid message format or parameters
401	Unauthorized — invalid or missing API key
403	Forbidden — query blocked by restriction rule
429	Rate limit exceeded
500	Internal server error

See Error Codes for the complete list.

Authentication Query Endpoint