Chat Completions API — POST /v1/chat/completions Guide

POST /v1/chat/completions — create chat completions for any model including GPT, Claude, and Gemini using the OpenAI-compatible request format.

The /v1/chat/completions endpoint is the primary interface for generating text with any chat model on KiosAPI — including GPT, Claude, Gemini, and others. Every model uses the same standard OpenAI request format, so you can switch between providers by changing the model field alone, with no other code changes required.

OpenAI, Claude, Gemini, and other chat models all share this endpoint format. For a full parameter reference and advanced usage patterns, see the official OpenAI Chat API documentation.

Request

Endpoint: POST https://kiosapi.com/v1/chat/completions

Headers

Header	Value	Description
Content-Type	application/json	Required for all requests
Authorization	Bearer sk-xxx	Your KiosAPI key

Request Body

model · string · required

The model to use for the completion, e.g. gpt-4o. You can retrieve the full list of available model IDs from the List Models endpoint.

messages · array · required

An ordered array of message objects forming the conversation history.

Show messages[]

messages[].role · string · required

The role of the message author. Accepted values: system, user, or assistant.

messages[].content · string · required

The text content of the message.

temperature · number

Sampling temperature between 0 and 2. Higher values produce more varied output; lower values produce more deterministic output. Defaults to 1.

top_p · number

Nucleus sampling probability mass. An alternative to temperature — only tokens comprising the top top_p probability mass are considered. Avoid setting both temperature and top_p at the same time.

stream · boolean

When true, the response is streamed back as server-sent events. Defaults to false.

max_tokens · number

The maximum number of tokens to generate in the completion. The request will be cut off once this limit is reached.

n · number

How many independent completion choices to generate for each request. Defaults to 1.

presence_penalty · number

A value between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the conversation so far, increasing the model’s likelihood to introduce new topics.

frequency_penalty · number

A value between -2.0 and 2.0. Positive values penalize new tokens based on their frequency in the conversation so far, reducing repetition.

response_format · object

Configuration object for structured output. For example, set { "type": "json_object" } to enable JSON mode.

stop · array

One or more sequences at which the model will stop generating further tokens. Accepts a string or an array of up to four strings.

user · string

An opaque identifier representing your end user. Useful for abuse monitoring and associating completions with specific users in your system.

Examples

cURL

curl https://kiosapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxx" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "Hello world!"
      }
    ],
    "max_tokens": 1688,
    "temperature": 0.5,
    "stream": false
  }'

Python

import openai

openai.api_key = "sk-xxx"
openai.base_url = "https://kiosapi.com/v1/"

completion = openai.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Hello world!"}
    ],
    max_tokens=1688,
    temperature=0.5,
    stream=False
)

print(completion.choices[0].message.content)

Response

A successful request returns a chat completion object containing the generated message along with token usage statistics.

{
  "id": "chatcmpl-A1iMgDLzZtUJ9QDpfqDLxKH0zfUnp",
  "object": "chat.completion",
  "created": 1724972230,
  "model": "gpt-4o-2024-05-13",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello there! How can I assist you today?",
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 10,
    "total_tokens": 19
  },
  "system_fingerprint": "fp_157b3831f5"
}

Response Fields

id · string · required

Unique identifier for this completion, prefixed with chatcmpl-.

object · string · required

Always "chat.completion".

created · integer · required

Unix timestamp (seconds) of when the completion was created.

model · string · required

The exact model version used to generate the response, which may differ from the model ID you requested.

choices · array · required

Array of completion choices. Contains one entry by default, or more if you set n greater than 1.

Show choices[]

choices[].index · integer · required

Zero-based index of this choice in the array.

choices[].message.role · string · required

Always "assistant".

choices[].message.content · string · required

The generated text response from the model.

choices[].finish_reason · string · required

The reason generation stopped. Common values: stop (natural end), length (hit max_tokens), tool_calls (model called a tool).

usage · object · required

Token consumption for this request, useful for cost tracking.

Show usage

usage.prompt_tokens · integer · required

Number of tokens in the input messages.

usage.completion_tokens · integer · required

Number of tokens in the generated response.

usage.total_tokens · integer · required

Sum of prompt_tokens and completion_tokens.