# Chat completions

Send messages to `POST /v1/chat/completions`. Without streaming, the API returns a JSON completion after generation finishes.

## A complete request

This example uses a model listed in the public catalogue on 2026-09-14. Replace the ID if your integration uses another model.

~~~bash
curl --fail-with-body https://api.simplellm.eu/v1/chat/completions \
  -H "Authorization: Bearer $SIMPLELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-flash-next",
    "messages": [
      {"role": "system", "content": "You explain programming concepts concisely."},
      {"role": "user", "content": "Explain the difference between a queue and a stack."}
    ],
    "temperature": 0.3,
    "max_tokens": 2048,
    "stream": false
  }'
~~~

## Messages and conversation history

Use a `system` message for persistent instructions, `user` for input, and `assistant` for prior model responses. Tool-enabled conversations also use `tool` messages.

Chat completions do not supply a conversation-storage API: your application sends the relevant history with each request. A follow-up can look like this:

~~~json
{
  "model": "qwen3.8-flash-next",
  "messages": [
    {"role": "system", "content": "Use concise examples."},
    {"role": "user", "content": "What is a stack?"},
    {"role": "assistant", "content": "A stack removes the most recently added item first."},
    {"role": "user", "content": "Show one in Python."}
  ],
  "max_tokens": 2048
}
~~~

Keep your own system instructions in subsequent requests. V1 can apply a configured model system prompt when no system message is supplied; send an explicit system message when your application needs to control it.

## Generation parameters

| Parameter | Purpose | Integration guidance |
| --- | --- | --- |
| `model` | Select the model | Required; use an exact catalogue ID |
| `messages` | Conversation input | Required, nonempty array |
| `max_tokens` | Output budget | Positive integer; reasoning may consume it |
| `temperature` | Sampling variability | Accepted range and behavior depend on the model |
| `top_p` | Nucleus sampling | Tune one sampling control at a time |
| `stream` | Incremental delivery | Defaults to false |
| `stop` | Stop sequences | Use an array of strings in V1, not a single string |
| `tools` / `tool_choice` | Function-call interface | Requires tool-capable model behavior |
| `response_format` | Requested output structure | Forwarded option; support is model-dependent |

Avoid assuming upstream-specific options work for every model. The [HTTP reference](/docs/reference/createChatCompletion.html) documents the request and response structure.

## Read the result

Read `choices[0].message.content` for a regular text response. Preserve `tool_calls` when a tool-capable model asks your application to run a function.

| Common finish reason | Interpretation |
| --- | --- |
| `stop` | Normal completion or a stop condition |
| `length` | Output budget reached; result can be incomplete |
| `tool_calls` | Model requested a tool; continue the tool loop |
| null in stream chunks | Generation has not yet supplied a final reason |

The exact finish reasons and optional response fields depend on the model and provider. Inspect `usage` separately from visible text; output tokens can include reasoning.

## Next steps

[Stream output](/docs/streaming.html), [add tools](/docs/tools.html), or [send an image](/docs/vision.html). For a long-running application, implement [cancellation and retry handling](/docs/limits.html) before increasing concurrency.