Chat Completions
Chat completion API
The Chat Completions API lets you build conversation-based AI applications. By sending message history, you get contextual and consistent responses.
/v1/chat/completions
Generates a model response for the given message history.
Request Body
The ID of the model to use. Example: google/gemini-3.8-flash, anthropic/claude-sonnet-5.5, openai/gpt-6-luna
An array of messages containing the conversation history. Each message must include the role and content fields.
A value between 0 and 2. Higher values produce more creative responses, lower values more consistent ones. Default: 0.7
The maximum number of tokens to generate in the response. On reasoning models, thinking tokens also count toward this limit; a very small value can cut the answer short (finish_reason: "length"). If it is not sent, the balance pre-check uses the model's maximum output tokens; set a suitable ceiling to avoid 402 with a low balance.
When set to true, responses are streamed in real time as Server-Sent Events. Default: false
The nucleus sampling parameter. Between 0 and 1. Default: 1
OpenAI's newer name for max_tokens. If max_tokens is not sent, this field is used instead; if both are sent, max_tokens wins. Some models raise very small values to their own minimum (for example 16).
Up to 4 sequences (a string or an array of strings) where generation stops. On reasoning models a sequence can also match inside the reasoning text, so the response may end with content: null; some models (for example OpenAI's reasoning models) ignore stop.
Functions the model may call (OpenAI tools format). If the model calls a tool, the response carries choices[0].message.tool_calls and finish_reason is tool_calls. Send the tool result in the next request with role: "tool" and tool_call_id. When streaming, tool calls arrive as delta.tool_calls chunks. Tool definitions are billed as input tokens.
auto (default), none, required or a specific function: {"type": "function", "function": {"name": "..."}}. parallel_tool_calls is passed through as well.
{"type": "json_object"} returns a valid JSON object; {"type": "json_schema", "json_schema": {"name": "...", "strict": true, "schema": {...}}} returns JSON that matches the schema. Also ask for JSON in your prompt. On reasoning models keep max_tokens high enough to cover the reasoning as well; otherwise the JSON can be cut short (finish_reason: "length").
Reasoning level: none, minimal, low, medium, high. It has an effect on reasoning models and is ignored by models that do not support it. none turns reasoning off (faster, cheaper answers). Reasoning tokens are billed as output tokens.
Detailed reasoning settings: {"effort": "low"}, {"max_tokens": 1024} or {"exclude": true}. If sent, it takes precedence over reasoning_effort. If the model produced reasoning text, it is returned in message.reasoning (delta.reasoning when streaming).
Note: n (multiple choices), logprobs, top_logprobs, logit_bias, seed and user are currently not passed through on paid models; the response has a single choice. top_k, frequency_penalty and presence_penalty are passed through. For the extra parameters of the free Türkiye models (:tr), see Türkiye models.
Model Names and Aliases
/v1/chat/completionsrequires the full catalog id (provider/model); if the id is not in the catalog, it returns 400unsupported_model.- The
~anthropic/claude-sonnet-latest,~anthropic/claude-opus-latestand~anthropic/claude-haiku-latestaliases always point to the current model of that family. - The Responses and Anthropic Messages endpoints also resolve unprefixed names that match exactly one catalog model; the Messages endpoint maps Anthropic ids (
claude-sonnet-5-5) to their catalog counterpart.
Balance pre-check: before the request reaches the model, the estimated maximum cost is compared with your balance. The estimate is computed from the input and max_tokens (the model's maximum output tokens if not sent) plus a 20% safety buffer; if your balance is below it, 402 is returned. You are always charged for actual usage. Details: Error Codes.
Message Roles
| Role | Description |
|---|---|
system |
A system instruction that defines the assistant's behavior |
user |
Messages from the user |
assistant |
The assistant's previous responses |
Example Request
curl https://api.onysoft.com/v1/chat/completions \
-H "Authorization: Bearer sk-ony-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemini-3.8-flash",
"messages": [
{
"role": "system",
"content": "Sen yardımcı bir asistansın."
},
{
"role": "user",
"content": "Python'da liste nasıl oluşturulur?"
}
],
"temperature": 0.7,
"max_tokens": 2000
}'
Example Response
{
"id": "req_a1b2c3d4e5f6a1b2c3d4e5f6",
"object": "chat.completion",
"created": 1706000000,
"model": "google/gemini-3.8-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Python'da liste oluşturmanın birkaç yolu vardır:\n\n1. Köşeli parantez ile:\n```python\nmy_list = [1, 2, 3, 4, 5]\n```\n\n2. list() fonksiyonu ile:\n```python\nmy_list = list((1, 2, 3))\n```"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 95,
"total_tokens": 123
},
"cost": {
"amount": 0.000061,
"currency": "USD"
},
"success": true,
"data": { /* backward compatibility: the same fields as above (id, object, created, model, choices, usage, cost) */ }
}
In non-streaming responses the OpenAI fields (id, choices, usage …) are at the top level, so the official OpenAI SDKs and libraries such as LangChain read response.choices[0].message.content directly. For backward compatibility the response also carries "success": true and the same content under data; existing integrations that read data.choices keep working unchanged. Use the top-level fields in new integrations. The request's charge is in the cost.amount field (USD). In non-streaming responses that contain generated images or audio, clients other than the official SDKs receive only the "success": true + data form so that the response size does not double.