Chat completions

Creates a chat completion for the given conversation messages.

Send requests to POST /v1/chat/completions on the API host (production: https://api.rikaii.com). Paths are relative to that host unless your integration uses a custom base URL.

Request and response bodies follow the OpenAI Chat Completions JSON shape so official OpenAI SDKs can often be pointed at Rikaii with minimal configuration—same top-level fields (model, messages, temperature, max_tokens, stream) and the familiar completion object on success.

Note on Models

Rikaii accepts the model parameter to maintain 100% compatibility with official OpenAI SDKs. However, Rikaii's Smart Routing Engine intercepts each request and dynamically routes it to the optimal provider based on your Dashboard configuration—routing rules, fallback behavior, and keyword triggers—not solely on the model string in the payload.

Endpoint

POST /v1/chat/completions

Example URL: https://api.rikaii.com/v1/chat/completions

Headers

Header	Required	Description
Authorization	Yes	Bearer <api-key> — see Authentication
Content-Type	Yes	application/json

Request body

Field	JSON key	Type	Required	Description
model	model	string	No	Accepted for OpenAI SDK compatibility; routing follows your dashboard rules (see note above).
messages	messages	array	Yes	Conversation turns (see Messages below).
temperature	temperature	number	No	Sampling temperature.
max_tokens	max_tokens	integer	No	Maximum tokens to generate in the reply.
stream	stream	boolean	No	true streams the completion; omit or false for a single JSON response.

Parameters & forwarding (OpenAI-compatible)

When you include temperature, max_tokens, or stream in the JSON body, Rikaii forwards them on upstream provider calls (OpenAI-shaped payloads use the same field names). Streaming requests set stream: true (and related streaming options where the upstream API requires them). Provider adapters that use different schemas—such as Anthropic’s Messages API—map these knobs to the equivalent upstream parameters (temperature, max_tokens, stream) rather than dropping them.

Messages

Each item in messages is an object with:

Field	Type	Description
role	string	Typically system, user, or assistant.
content	string	Message text for that turn.

Advanced OpenAI features such as tool calling may use additional fields in OpenAI’s own API; only role and content are documented here as the portable subset for Rikaii chat requests.

Request schema (reference)

{
  "type": "object",
  "properties": {
    "model": { "type": "string" },
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": { "type": "string" },
          "content": { "type": "string" }
        },
        "required": ["role", "content"]
      }
    },
    "temperature": { "type": "number" },
    "max_tokens": { "type": "integer" },
    "stream": { "type": "boolean" }
  }
}

Example payload

{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "system", "content": "You are a concise assistant." },
    { "role": "user", "content": "Give two benefits of using a unified LLM API." }
  ],
  "max_tokens": 256,
  "temperature": 0.2
}

Response

On success, 200 OK with application/json in the shape of an OpenAI chat completion:

Field	JSON key	Description
id	id	Completion identifier.
object	object	Object type (e.g. chat.completion).
created	created	Unix timestamp.
model	model	Model identifier returned for this completion.
choices	choices	Includes message, finish_reason, etc.
usage	usage	prompt_tokens, completion_tokens, total_tokens.

Responses may include extra fields from upstream providers; treat unknown keys as optional.

Example response

{
  "id": "chatcmpl_…",
  "object": "chat.completion",
  "created": 1735689600,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 28,
    "total_tokens": 70
  }
}

X-Rikaii-Fallback

When a fallback route is used to fulfill the request, the response may include:

X-Rikaii-Fallback: true

Streaming

Set stream to true to receive a text/event-stream (SSE) response. Parse events using your HTTP client; chunks follow the usual streaming chat-completion pattern.

Examples

cURL

curl -sS "https://api.rikaii.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Ping"}
    ],
    "max_tokens": 16
  }'

Node.js

const res = await fetch('https://api.rikaii.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'Ping' }],
    max_tokens: 16,
  }),
})

if (!res.ok) {
  const err = await res.text()
  throw new Error(`HTTP ${res.status}: ${err}`)
}

const data = await res.json()
console.log(data.choices[0]?.message?.content)

Related

• Authentication
• Errors
• Models