# Create a chat completion

`POST /v1/chat/completions`

Creates a model response for the given chat conversation. Supports vision image_url inputs, reasoning, tool calling, and structured outputs when declared by the model. Vision processor limits are model-specific. Compatible with OpenAI's chat completions API.

## Authentication

Send `Authorization: Bearer $KOSCOMPUTE_API_KEY`.

## Request

Content type: `application/json`

| Field | Type | Required | Description |
|---|---|---:|---|
| `model` | string | Yes | Canonical model ID from GET /v1/models |
| `messages` | array | Yes | See the endpoint guide for behavior and model support. |
| `temperature` | number | No | See the endpoint guide for behavior and model support. |
| `top_p` | number | No | See the endpoint guide for behavior and model support. |
| `top_k` | integer | No | See the endpoint guide for behavior and model support. |
| `min_p` | number | No | See the endpoint guide for behavior and model support. |
| `frequency_penalty` | number | No | See the endpoint guide for behavior and model support. |
| `presence_penalty` | number | No | See the endpoint guide for behavior and model support. |
| `repetition_penalty` | number | No | See the endpoint guide for behavior and model support. |
| `max_tokens` | integer | No | Legacy alias for max_completion_tokens. It limits all completion tokens, including reasoning. If both fields are present, their values must match. |
| `max_completion_tokens` | integer | No | Hard maximum for all completion tokens, including reasoning and visible output. |
| `stop` | string · array | No | See the endpoint guide for behavior and model support. |
| `seed` | integer | No | See the endpoint guide for behavior and model support. |
| `logit_bias` | object | No | See the endpoint guide for behavior and model support. |
| `logprobs` | boolean | No | See the endpoint guide for behavior and model support. |
| `top_logprobs` | integer | No | See the endpoint guide for behavior and model support. |
| `stream` | boolean | No | See the endpoint guide for behavior and model support. |
| `stream_options` | object | No | See the endpoint guide for behavior and model support. |
| `response_format` | ResponseFormat | No | See the endpoint guide for behavior and model support. |
| `tools` | array | No | See the endpoint guide for behavior and model support. |
| `tool_choice` | string · object | No | See the endpoint guide for behavior and model support. |
| `reasoning` | object | No | Reasoning controls. The reasoning sub-budget never increases max_completion_tokens. |
| `reasoning_effort` | string | No | Top-level alias for reasoning.effort. Model-specific canonical effort sets are published per-model in GET /v1/models (model_info.supported_reasoning_efforts). Values: `none`, `low`, `medium`, `high`, `xhigh`. |
| `include_reasoning` | boolean | No | See the endpoint guide for behavior and model support. |
| `user` | string | No | See the endpoint guide for behavior and model support. |

## Examples

### cURL

```bash
curl https://api.koscompute.com/v1/chat/completions \
  -H "Authorization: Bearer $KOSCOMPUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen/qwen3.8-27b","messages":[{"role":"user","content":"Reply with one sentence."}],"max_completion_tokens":120}'
```

### Python

```python
import os
import requests

response = requests.post(
    "https://api.koscompute.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['KOSCOMPUTE_API_KEY']}"},
    json={
  "model": "qwen/qwen3.8-27b",
  "messages": [
    {
      "role": "user",
      "content": "Reply with one sentence."
    }
  ],
  "max_completion_tokens": 120
},
)
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.koscompute.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOSCOMPUTE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"model":"qwen/qwen3.8-27b","messages":[{"role":"user","content":"Reply with one sentence."}],"max_completion_tokens":120}),
});
console.log(await response.json());
```

## Responses

| Status | Meaning |
|---:|---|
| `200` | Successful response |
| `400` | Bad request — invalid parameters or payload |
| `401` | Invalid or missing API key |
| `403` | Model not allowed for this API key |
| `404` | Public model not found |
| `413` | Request body exceeds the limit |
| `429` | Rate limit or admission capacity is full. The message states when to retry; vision saturation also reports active/total vision concurrency. |
| `502` | Invalid or failed upstream response |
| `503` | No healthy route |
| `504` | Backend generation timeout |
| `500` | Internal server error |

## Next steps

Use the endpoint guide for complete workflows, model capability notes, streaming behavior, and retry advice.