---
title: "Create a chat completion."
method: POST
path: "/v1/ai/chat/completions"
tags: ["AI"]
---

# Create a chat completion.

`POST /v1/ai/chat/completions`

## Request

- Base URL: `https://api.scalix.world`
- URL: `https://api.scalix.world/v1/ai/chat/completions`
- Auth: HTTP bearer

Runs an OpenAI-compatible chat completion and returns the model's response.

## Request body

- ChatCompletionRequest: A chat-completion request (OpenAI-compatible). Streams via SSE when `stream`.
  - `messages` ChatMessage[], required
    - `role` string, required: One of `system`, `user`, `assistant`.
    - `content` string, required
  - `model` string, required
  - `max_tokens` integer, nullable
  - `temperature` number, double, nullable
  - `top_p` number, double, nullable
  - `stream` boolean, nullable

## Response `200`

Completion response

- ChatCompletionResponse: A chat-completion response (OpenAI-compatible envelope).
  - `id` string, required
  - `object` string, required
  - `created` integer, required
  - `model` string, required
  - `choices` ChatCompletionChoice[], required: Completion choices; each carries an index, a message, and a finish reason.
    - `index` integer, required: Choice index.
    - `message` ChatCompletionMessage, required: A single chat message (OpenAI-compatible).
      - `role` string, required: Message author role.
      - `content` string, required: Message content.
    - `finish_reason` string, nullable: Why generation stopped (`stop`, `length`, `tool_calls`, …).
  - `usage` ChatCompletionUsage, required: Token usage accounting (prompt/completion/total).
    - `prompt_tokens` integer, required: Prompt tokens consumed.
    - `completion_tokens` integer, required: Completion tokens generated.
    - `total_tokens` integer, required: Total tokens.

## Other responses

- `401`: Missing or invalid API key
- `402`: Budget exhausted
- `500`: Internal error
- `503`: All providers exhausted

---

[API](https://skmtc.dev/scalix/apis/scalix-cloud-api.md) · [All operations](https://skmtc.dev/scalix/apis/scalix-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalix/apis/scalix-cloud-api/revisions/2c04ca0a90bb?raw)