OpenAI API documentation in plain terms: Chat Completions by parameter

If you are looking for OpenAI API documentation in plain terms, you usually need one endpoint: POST /v1/chat/completions. Chatbots, agents and most integrations work through it, and its format has long become common to other providers. Below we go through it by parameter: what to send, what comes back, how to read usage, and what nuances appear when working through a gateway. Always check the full description in the official OpenAI API reference: it keeps changing, and this text is a short cheat sheet.

The examples use the OpenAI SDK with the gateway address https://api.zukko.pro/v1. Against OpenAI itself only the address and key differ, the request shape is the same. Prices below are as of October 18, 2026.

A minimal request

Two parameters are required: model and messages.

from openai import OpenAI

client = OpenAI(base_url="https://api.zukko.pro/v1", api_key="fetch_your_key")

resp = client.chat.completions.create(
    model="gpt-6.1-sol",
    messages=[
        {"role": "system", "content": "Answer briefly."},
        {"role": "user", "content": "What is a token?"},
    ],
    max_tokens=300,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

Request parameters

messages

Each message is an object with role and content. The system role sets rules, user carries the request, assistant holds earlier model replies, and tool holds a function call result. The model does not remember earlier requests: the whole conversation history is sent again with every request, which is exactly why long conversations get more expensive.

temperature and top_p

The OpenAI docs recommend changing one or the other, not both. Not every model accepts non-default values. The Zukko reference says separately that new Claude models may reject a non-default temperature, so it is better not to pass it for them.

max_tokens

It limits the reply length and helps avoid paying for extra output. In the OpenAI reference max_tokens is marked deprecated in favor of max_completion_tokens, which also covers reasoning tokens. The Zukko reference describes max_tokens, so use it and test max_completion_tokens on your model with a separate request. If the reply is cut off, look at finish_reason: the value length means the limit was reached.

stream

With stream=True the reply arrives in pieces. The last piece before [DONE] carries usage and an empty choices array, so check that the list is not empty before reading choices[0]:

stream = client.chat.completions.create(
    model="gpt-6.1-sol",
    messages=[{"role": "user", "content": "Name three colors"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

More about streaming in the article when you need stream: true↗.

tools and tool_choice

With tools you describe functions using a JSON schema. The model does not run them: it returns a function name and arguments, and your code has to perform the call.

tools = [{
    "type": "function",
    "function": {
        "name": "get_rate",
        "description": "Currency rate to rubles",
        "parameters": {
            "type": "object",
            "properties": {"code": {"type": "string", "description": "Currency code, for example USD"}},
            "required": ["code"],
        },
    },
}]

messages = [{"role": "user", "content": "How much is a dollar?"}]

tool_choice controls the choice: none forbids calls, auto leaves the decision to the model, required demands at least one call, and an object with a function name forces that function. Not all models and gateways support forcing equally, so test it on your model. Differences between model families are covered in function calling in Claude, GPT and Qwen↗.

response_format

{"type": "json_object"} turns on JSON mode: the reply is valid JSON, and the prompt must contain the word JSON. {"type": "json_schema", ...} gives structured output by schema and is called preferred in the OpenAI reference where the model supports it. Which variant a particular model accepts on the gateway should be checked with a test request, and the result should still be parsed with error handling.

Response format

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-6.1-sol",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "A token is ..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 30, "completion_tokens": 150, "total_tokens": 180}
}

finish_reason values: stop is a natural finish, length means the limit was reached, tool_calls means the model asks to call a function, content_filter means a filter fired. For GPT models usage may include prompt_tokens_details.cached_tokens, the number of input tokens read from cache.

What one reply costs

Take the reply from the example: 30 input tokens and 150 output tokens on gpt-6.1-sol (input 0.27, output 1.32 dollars per million). Formula: input × input price + output × output price.

30 × 0.27 / 1,000,000 + 150 × 1.32 / 1,000,000 = 0.0000081 + 0.000198 ≈ $0.000206.

One such reply costs about two hundredths of a cent, and totals grow with the length of history and reply. The current list of models and prices: GET https://api.zukko.pro/v1/models or the "Models" page in your account.

Errors

• 401: wrong key.
• 402: not enough balance.
• 403 model_not_allowed_for_key: the model is not allowed for the key.
• 404 model_not_found: unknown model name.
• 413: request too large.
• 429: the key's daily or monthly limit is exhausted, or a limit at the model provider.
• 503: provider unavailable or model switched off (model_disabled).

Details are in the chat completions reference↗. If you are choosing between this endpoint and /v1/responses, read the comparison of the two APIs↗.

FAQ

How does the OpenAI documentation differ from the gateway documentation?

OpenAI describes every capability of its platform, including those only it has: files, batch processing, embeddings. The gateway documentation describes what is available in the gateway itself: chat requests, the model list, the response format and errors. Check parameters against it.

Where do I get a key and the address?

Create a key in your account↗; the address for the OpenAI format is https://api.zukko.pro/v1. The examples in this article work from Russia unchanged, and the balance is topped up via SBP, MasterCard or crypto.

Why does a parameter that works with OpenAI fail on another model?

Parameters share the same shape, but support depends on the model. If a request is rejected, remove the parameter and check the reply, then add parameters back one at a time.

Do I need to send the conversation history?

Yes. The model keeps no state between requests: the client sends the whole history again.