Sampling

⚠️

Preview — this feature is being built; the design below is the spec.

Sampling settings change how the model picks each next word. Lower values make replies more focused and repeatable; higher values make them more varied. Not every model allows every setting, so each model lists what it supports, and the API tells you plainly when a setting cannot be honoured instead of ignoring it.

Today: temperature, top_p, n, presence_penalty and frequency_penalty are accepted and silently removed before the request reaches the model. The design below replaces that with per-model support and a clear 400.

The settings

Field	Range	Default	Effect
`temperature`	0.0 to 2.0	model default (usually 1.0)	Lower = more predictable, higher = more varied. `0` is close to deterministic but not guaranteed identical.
`top_p`	0.0 to 1.0	1.0	Only consider the most likely words whose probabilities add up to `top_p`.
`top_k`	1 to 500	off	Only consider the `top_k` most likely words. Advanced; most callers never need it.
`presence_penalty`	-2.0 to 2.0	0	Push the model towards new topics.
`frequency_penalty`	-2.0 to 2.0	0	Discourage repeating the same words.
`seed`	integer	none	Best-effort repeatability for identical requests.

Change either temperature or top_p, not both. Sending both to a model that only allows one returns 400 conflicting_parameters.

When to change them

Task	Suggested setting
Extraction, classification, code, tool use	`temperature` 0 to 0.3
General assistant replies	Leave the default
Brainstorming, naming, creative writing	`temperature` 1.0 to 1.3

Models with reasoning turned on often fix their sampling. Their capability flags say so.

Which models support what

Each model in GET /v1/models carries capability flags:

{
  "id": "Amara S1.2",
  "capabilities": {
    "temperature": true,
    "top_p": true,
    "top_k": false,
    "penalties": false,
    "seed": false
  }
}

The API checks every request against those flags:

You send	Model supports it	Result
A setting	Yes	Honoured.
A setting	No	`400 unsupported_parameter`, with the field name in `param`.
A setting	No, and header `syntic-ignore-unsupported: true`	Removed; the reply carries header `x-syntic-ignored-params: temperature,top_p`.
Nothing	—	Model defaults.

The opt-in header exists for code ported from other services that always sends sampling values. New code should not need it.

n (several choices per request) is not supported on any model; values other than 1 return 400 unsupported_parameter.

Example

curl https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Amara S1.2",
    "stream": false,
    "temperature": 1.2,
    "messages": [{ "role": "user", "content": "Ten names for a mobile bike repair van." }]
  }'

const resp = await fetch('https://app.syntic.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'Amara S1.2',
    stream: false,
    temperature: 1.2,
    messages: [{ role: 'user', content: 'Ten names for a mobile bike repair van.' }],
  }),
})
const data = await resp.json()
if (resp.status === 400 && data.error.code === 'unsupported_parameter') {
  console.warn(`Model does not support ${data.error.param}; retrying without it`)
}

import os, requests
 
body = {
    "model": "Amara S1.2",
    "stream": False,
    "temperature": 1.2,
    "messages": [{"role": "user", "content": "Ten names for a mobile bike repair van."}],
}
resp = requests.post(
    "https://app.syntic.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}"},
    json=body,
    timeout=60,
)
data = resp.json()
if resp.status_code == 400 and data["error"]["code"] == "unsupported_parameter":
    body.pop(data["error"]["param"], None)  # drop the setting and try again

Errors

Envelope: Error format.

{
  "error": {
    "type": "invalid_request",
    "code": "unsupported_parameter",
    "message": "This model does not accept 'top_k'. Remove it or send 'syntic-ignore-unsupported: true'.",
    "param": "top_k"
  },
  "request_id": "req_01JBX7M3"
}

Status	`code`	Cause
400	`unsupported_parameter`	The model does not support the setting.
400	`out_of_range`	Value outside the range in the table above.
400	`conflicting_parameters`	Both `temperature` and `top_p` sent to a model that allows only one.

Build notes for the platform team

Add supports_temperature, supports_top_p, supports_top_k, supports_penalties, supports_seed to chat.models; expose them as capabilities on /v1/models.
Replace the current strip-all handling of sampling fields with the check above. Validation runs before billing.
Log the count of unsupported_parameter errors per key for the first month after launch to spot breaking integrations.

Request parameters Stop reasons

Was this page helpful?