---
title: "Chat Completions"
description: "POST /v1/chat/completions — Generate text with Liutong models"
---

Generate model responses for a conversation. This is the primary endpoint for text generation with `crimson-falcon-4`, `indigo-owl-4`, and `amber-phoenix-4`.

## Endpoint

```
POST /v1/chat/completions
```

## Request body

| Parameter | Type | Required | Description |
|---|---|---|---|
| `model` | string | Yes | Model ID (e.g., `crimson-falcon-4`). |
| `messages` | array | Yes | Array of message objects. |
| `temperature` | float | No | Sampling temperature (0-2). Default: 1.0. |
| `top_p` | float | No | Nucleus sampling. Default: 1.0. |
| `max_tokens` | int | No | Max tokens to generate. |
| `stream` | bool | No | Stream partial responses via SSE. Default: false. |
| `stop` | string/array | No | Stop sequence(s). |
| `n` | int | No | Number of completions. Default: 1. |

### Message object

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | string | Yes | `system`, `user`, or `assistant`. |
| `content` | string | Yes | The message content. |

## Example request

```bash
curl https://api.liutong.llby.org/v1/chat/completions \
  -H "Authorization: Bearer lt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "crimson-falcon-4",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain quantum entanglement in simple terms."}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'
```

## Response

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "crimson-falcon-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum entanglement is..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}
```

## Streaming

Set `stream: true` to receive partial responses as server-sent events (SSE):

```bash
curl https://api.liutong.llby.org/v1/chat/completions \
  -H "Authorization: Bearer lt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "crimson-falcon-4",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'
```

Each SSE event contains a chunk:

```
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: [DONE]
```

## Error responses

| Status | Description |
|---|---|
| 401 | Invalid or missing API key. |
| 400 | Malformed request body. |
| 404 | Model not found. |
| 429 | Rate limit exceeded. |
| 500 | Internal server error. |