# Parameters

The fields that shape how a text model writes its reply, with the range each takes.

## Request

Send them with an API key, in the body of `POST /v1/chat/completions`, beside `model` and
`messages`. [Chat](/docs/reference/chat-completions) lists the route's other fields, and the
[Text](/docs/text) guide walks through a first call. Every field here is optional.

A field you leave out is not filled in: the provider that serves the model applies its own
default. *You send* names the usual one. A field the provider does not take is ignored, unless
`provider.require_parameters` is `true`: then only a provider that takes every field you sent
serves the request. `tools`, `response_format` and `verbosity` already steer the request to the
providers that take them, where some do. Each model's catalogue entry lists the fields its
providers take, in `supported_parameters` ([`GET /v1/models`](/docs/reference/models)).

Souk Bot answers customers of a clothing shop in Oran. Yacine keeps its replies short and
steady:

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "Do you have this jacket in size M?"

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "messages": [{"role": "user", "content": PROMPT}],
            "temperature": 0.3,
            "max_tokens": 300,
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

print(answer["choices"][0]["message"]["content"])
print(answer["choices"][0]["finish_reason"])
print(answer["usage"]["cost"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/chat/completions";
const MODEL = "anthropic/claude-sonnet-4.5";
const PROMPT = "Do you have this jacket in size M?";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    messages: [{ role: "user", content: PROMPT }],
    temperature: 0.3,
    max_tokens: 300,
  }),
});
const answer = await response.json();

console.log(answer.choices[0].message.content);
console.log(answer.choices[0].finish_reason);
console.log(answer.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address = "https://opendunes.com/v1/chat/completions"
	model   = "anthropic/claude-sonnet-4.5"
	prompt  = "Do you have this jacket in size M?"
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	body, err := json.Marshal(map[string]any{
		"model": model,
		"messages": []map[string]string{
			{"role": "user", "content": prompt},
		},
		"temperature": 0.3,
		"max_tokens":  300,
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var answer struct {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
			FinishReason string `json:"finish_reason"`
		} `json:"choices"`
		Usage struct {
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}

	fmt.Println(answer.Choices[0].Message.Content)
	fmt.Println(answer.Choices[0].FinishReason)
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/chat/completions"
MODEL="anthropic/claude-sonnet-4.5"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {"role": "user", "content": "Do you have this jacket in size M?"}
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'
```

### Sampling

| Field | Needed | You send |
|---|---|---|
| `temperature` | no | 0 to 2, usually 1: lower is more predictable, higher more varied; at 0 the same prompt gives the same reply |
| `top_p` | no | 0 to 1, usually 1: sample only from the likeliest tokens that together reach this share |
| `top_k` | no | 0 or more, usually 0, which is off: sample only from this many likeliest tokens; 1 always takes the likeliest |
| `min_p` | no | 0 to 1, usually 0: drop tokens below this share of the likeliest token's probability |
| `top_a` | no | 0 to 1, usually 0: drop tokens far less likely than the likeliest one |
| `frequency_penalty` | no | -2 to 2, usually 0: above 0, a token is less likely the more often it has appeared; below 0, more likely |
| `presence_penalty` | no | -2 to 2, usually 0: above 0, a token is less likely once it has appeared at all, however often |
| `repetition_penalty` | no | 0 to 2, usually 1: above 1, repeated tokens are less likely; too high and the reply loses its small words |
| `seed` | no | a whole number that makes a repeat likelier to come out the same; never guaranteed |
| `logit_bias` | no | token ids mapped to a bias from -100 to 100: -1 to 1 nudges a token, -100 bans it, 100 forces it |
| `stop` | no | a list of strings: the reply ends before any of them |

### Tools

| Field | Needed | You send |
|---|---|---|
| `tools` | no | the tools the model may call, in the OpenAI shape; the model's provider receives them in its own. [Tools and function calling](/docs/tools) walks through a call |
| `tool_choice` | no | `none`, `auto`, `required`, or `{"type": "function", "function": {"name": ...}}` to force one tool |
| `parallel_tool_calls` | no | `true` or `false`, usually `true`: `false` has the model call one tool at a time |
| `web_search_options` | no | the settings of a model's own web search, where its provider has one |

### Output shape

| Field | Needed | You send |
|---|---|---|
| `max_tokens` | no | 1 or more: the most tokens the reply may hold, at most the model's context less the prompt. A model that reasons spends it on the reasoning too, and a small ceiling can end with `finish_reason: "length"` and no text |
| `max_completion_tokens` | no | the same ceiling, under its newer name |
| `reasoning` | no | how the model reasons, where it does: whether it reasons, how hard (`effort`), up to how many tokens (`max_tokens`), and whether its reasoning is left out of the reply (`exclude`) |
| `reasoning_effort` | no | `none`, `minimal`, `low`, `medium`, `high` or `xhigh`: the same level, as a single word |
| `include_reasoning` | no | `true` to return the reasoning in the reply; the older spelling of `reasoning.exclude: false` |
| `response_format` | no | `{"type": "json_object"}` for a reply that is always valid JSON; say so in the prompt too. `{"type": "json_schema", ...}` for JSON in your shape: [Structured outputs](/docs/structured-outputs) |
| `structured_outputs` | no | whether the model may answer to a `json_schema` in `response_format` |
| `logprobs` | no | `true` to receive each token's log probability |
| `top_logprobs` | no | 0 to 20: the likeliest alternatives to list for each token, with `logprobs: true` |
| `verbosity` | no | `low`, `medium`, `high`, `xhigh` or `max`, usually `medium`: how long and detailed the reply is |

On `POST /v1/responses` the ceiling is `max_output_tokens`, the reply's shape is
`text.format`, and `verbosity` is `text.verbosity`. On `POST /v1/messages` the ceiling is
`max_tokens`, `stop` is `stop_sequences`, and reasoning is `thinking`.

## Response

`200 OK`, in the route's own shape. On Chat the fields read:

| Field | Holds |
|---|---|
| `content` | in `choices[0].message`: the reply, shaped by the fields above |
| `finish_reason` | in `choices[0]`: `stop` when the reply ended or met a `stop` string, `length` when it reached `max_tokens`, `tool_calls` when it calls a tool |
| `logprobs` | in `choices[0]`: each token's log probability, and its `top_logprobs` alternatives, when `logprobs` asked for them |
| `reasoning` | in `choices[0].message`: the reasoning, where the model reasons and does not leave it out |
| `reasoning_tokens` | in `usage.completion_tokens_details`: the part of the reply's tokens spent reasoning |
| `cost` | in `usage`: the charge, in DA |

## What it cost

Charged in DA from your balance once the reply is delivered: the tokens the model reports, at
the model's rates, which its model page shows. `usage.cost` carries the charge.

- **Moves the count**: `max_tokens` and `max_completion_tokens`, the ceiling on what comes back;
  `reasoning` and `reasoning_effort`, whose tokens count as output, left out of the reply or
  not; `tools`, whose definitions are sent on every turn.
- **Changes the answer, never the bill**: the Sampling fields, `logprobs`, `top_logprobs`,
  `response_format`, `structured_outputs` and `tool_choice`.

A field changes no rate: the model, and the provider that serves it, set the rate.

## Errors

`error.code` carries the status, and `error.message` says why.

| Status | When |
|---|---|
| 400 | a field has the wrong type or is out of range, or the provider refused a field |
| 401 | the key is missing, wrong, disabled or expired |
| 402 | your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; `error.metadata.limit_source` names which, and `deposit_url` or `key_url` says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries `Retry-After: 60` |
| 404 | `model` is not a model on sale |
| 503 | no provider meets the routing you asked for: with `require_parameters`, none takes every field you sent |

What to do on each: [Errors and retries](/docs/errors-and-retries).
