API reference

Create a chat completion

POST /v1/chat/completions request, response, and error contract.

View Markdown

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¶

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¶

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¶

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.