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

# Create a chat completion

`POST /chat/completions`

## Request

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

Generate a chat completion with any of Krater's 500+ chat models. OpenAI-compatible request and response format, including streaming via server-sent events when stream is true. Credits are charged dynamically based on the model and token usage.

## Request body

- ChatCompletionRequest
  - `model` string, required: Model identifier, for example openai/gpt-4o-mini. Call listModels for the full catalog.
  - `messages` ChatMessage[], required: The conversation so far.
    - `role` 'system' | 'user' | 'assistant' | 'tool', required
    - `content` string, required: Message text.
  - `stream` boolean: Stream the response as server-sent events.
  - `temperature` number
  - `max_tokens` integer
  - `top_p` number
  - `frequency_penalty` number
  - `presence_penalty` number
  - `stop` union: Up to 4 sequences where generation stops.
    - string
    - string[]
  - `tools` object[]: OpenAI-style tool definitions for function calling.
    - `type` 'function', required
    - `function` object, required
      - `name` string, required
      - `description` string
      - `parameters` object: JSON Schema for the function arguments.
  - `tool_choice` union: Controls which tool the model may call.
    - 'none' | 'auto' | 'required'
    - object
  - `parallel_tool_calls` boolean

## Response `200`

Chat completion (JSON object, or a text/event-stream of chunks when stream is true).

- ChatCompletionResponse
  - `id` string, required
  - `object` 'chat.completion', required
  - `created` integer: Unix timestamp.
  - `model` string
  - `choices` object[], required
    - `index` integer
    - `message` ChatMessage
      - `role` 'system' | 'user' | 'assistant' | 'tool', required
      - `content` string, required: Message text.
    - `finish_reason` string
  - `usage` object
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer

## Other responses

- `400`: Invalid request body or parameters.
- `401`: Missing or invalid API key. Pass Authorization: Bearer kr_live_...
- `402`: Not enough credits, or the API key's daily credit cap is reached.
- `429`: Rate limit exceeded (default 60 requests per minute per key). Includes a Retry-After header.

---

[API](https://skmtc.dev/krater/apis/krater-api.md) - [All operations](https://skmtc.dev/krater/apis/krater-api/llms.txt) - [OpenAPI document](https://skmtc.dev/krater/apis/krater-api/revisions/66005541188c?raw)