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

# Create a chat completion

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.liquidcompute.co`
- URL: `https://api.liquidcompute.co/v1/chat/completions`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Generates a reply with the requested model, in OpenAI's chat
completions format. The key may be sent as `Authorization: Bearer` or
`X-API-Key`, never both.

With `stream: true` the reply is a server-sent event stream of
`chat.completion.chunk` objects ending with `data: [DONE]`; a
`: keep-alive` comment arrives during long silences, such as while a
long prompt is read. A stream that breaks off without `[DONE]` was cut
short and should be retried. Request fields other than those listed
are passed to the model's engine unchanged.

Requests of one conversation stay on the same GPU node, reusing its
prompt cache, when they share a `session_id` (or `X-Session-Id`
header), a `prompt_cache_key`, or their first system and user messages.

Completions are charged to your organization's API billing account:
without an active one, while it is paused, or once today's spend
reaches its daily limit, the answer is `402`.

Requires the `inference` entitlement family; requests without it
return `404` `not_found`.

## Headers

- `X-Session-Id` string

## Request body

- ChatCompletionRequest: An OpenAI chat completions request. Fields not listed here, such as `max_tokens`, `temperature` or `tools`, are passed to the model's engine unchanged.
  - `model` string, required: A model id from `GET /v1/models`.
  - `messages` object[], required
    - `role` string, required
    - `content` unknown
  - `stream` boolean
  - `stream_options` object
    - `include_usage` boolean: Send a final chunk with the request's token usage.
  - `session_id` string: Conversation id; requests sharing one stay on one GPU node.
  - `prompt_cache_key` string: Keeps requests on one GPU node when no session id is sent.

## Response `200`

The completion, or with `stream` set an event stream of completion chunks.

- ChatCompletion: An OpenAI chat completion as the model's engine produced it.
  - `id` string, required
  - `object` 'chat.completion', required
  - `created` integer
  - `model` string, required
  - `choices` object[], required
  - `usage` object
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer

## Other responses

- `400`: The request is not a valid chat completion (`invalid_request`), or the model's engine refused it; an engine's error is passed through as the engine wrote it.
- `401`: Missing or invalid API key, or both key headers sent.
- `402`: Your organization has no active API billing account (`billing_required`): add a card under Settings, API billing. Its completions are paused until a failed daily charge is paid (`billing_paused`). Or its spend today (UTC) reached its daily limit (`daily_limit_reached`): an admin can raise the limit, or retry after midnight UTC.
- `404`: The model is not served here (`model_not_found`), or the key's organization lacks the `inference` entitlement (`not_found`).
- `413`: The request body exceeds 16 MiB.
- `429`: Your key's rate limit was exceeded (`rate_limited`), your key already has as many completions in progress as its tier allows (`concurrency_limited`), or every GPU node serving the model is at capacity (`capacity_exhausted`); retry after `Retry-After`.
- `502`: The model router could not be reached or answered outside its contract (`upstream_error`); retry shortly.
- `503`: No GPU node is serving the model right now (`no_healthy_node`), the model router is still loading its catalogue (`warming_up`, with `Retry-After`), or API-key validation is temporarily unavailable (`service_unavailable`).

---

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