The shape of a first chat completion

Daily workEN2026-10-28

A chat completion starts with a simple exchange: your application sends a conversation to a model, and the model returns the next assistant message. The OpenAI chat completions format gives that exchange a common structure, so you do not need to learn a different request layout for every provider.

Here is the format on one page, with the pieces you need for a first working request.

§ The address and the envelope

A typical request uses the HTTP method POST and the path /v1/chat/completions. Its body is JSON. Two headers normally accompany it: Content-Type: application/json and Authorization: Bearer YOUR_API_KEY. Replace YOUR_API_KEY with a real key, and keep it on your server rather than exposing it in browser code.

Vana API provides an OpenAI-compatible endpoint at https://api.vanaapi.com. For a direct HTTP request, the full chat completions address is https://api.vanaapi.com/v1/chat/completions. When using an OpenAI SDK, configure its base URL as https://api.vanaapi.com/v1 and supply your Vana API key.

§ The smallest useful request

The two essential fields are model and messages. A minimal request body looks like this:

 1  {"model":"MODEL_ID","messages":[{"role":"user","content":"Explain a database index in two sentences."}]}

MODEL_ID is a placeholder. Replace it with the exact API identifier listed for your chosen model. A display name, such as Gemini 2.5 Flash, is not necessarily the string an API expects.

The messages field is an ordered array. Each entry says who is speaking and what they said. For a text-only introduction, content can be a plain string. Images and other inputs may use structured content parts, but support depends on the selected model and service.

§ Roles describe the conversation

system supplies broad instructions, such as “Use plain language and keep answers short.” Some models also support a developer role for application instructions; check compatibility before using it.
user contains the person’s question or request.
assistant contains a previous model reply that you are including as conversation history.
tool carries the result of a tool call, when your application supports tools.

For an ordinary follow-up, send the earlier user message, the assistant’s reply, and the new user message in that order. A basic chat completion request does not remember earlier calls automatically. Your application decides which history to include.

§ Reading the reply

A normal, non-streaming response contains a choices array. For a simple text answer, the value you usually want is choices[0].message.content. The first choice also has a finish_reason, which helps explain whether the reply ended normally, reached a limit, or requested a tool.

The response may also include usage, with token counts for the input and output. Tokens are pieces of text, not a fixed number of words. Sending more conversation history generally increases input usage.

Do not assume content always contains an answer. A tool-calling response can instead contain tool_calls. Your application executes permitted tools and sends their results back; the model does not execute your local functions by itself.

§ Settings to add gradually

stream: setting this to true requests incremental output. Read the arriving chunks rather than expecting one complete JSON response; text usually arrives through choices[0].delta.content.
temperature: where supported, lower values generally reduce variation. They do not guarantee identical answers.
Output limits: the accepted field can vary by model. Check support for max_completion_tokens or max_tokens rather than assuming they are interchangeable.

Start without optional settings, then add only what your application needs. OpenAI-compatible describes a shared interface, not identical capabilities across every model.

§ A practical first check

If a request fails, check the HTTP status and error body before changing the prompt. Confirm the key, model identifier, endpoint, and supported parameters. Keep credentials out of logs.

Create a Vana API account when you are ready to try a small request. Usage is billed per real token with no monthly fee. Begin with one message and a short answer; add conversation history and streaming after that basic exchange works.