Request parameters

Four settings shape almost every request: how long the reply may be, the instructions the model follows, where it must stop, and who the request is for. This page covers each one on POST /v1/chat/completions. The same fields exist on Messages with the names noted below.

Today only max_tokens and the system message reach the model; stop, user and metadata are accepted and ignored. This page is the design for honouring all of them.

At a glance

Endpoint and auth

POST https://app.syntic.ai/v1/chat/completions
Authorization: Bearer sk_live_...
Content-Type: application/json

max_tokens

The highest number of tokens the reply may contain. When generation reaches it, the reply ends and finish_reason is length.

• Must be a positive integer no larger than the model’s max_output_tokens (see Models). Larger values return 400 max_tokens_too_large instead of being clipped.
• Reasoning tokens count against it when reasoning is on.
• It caps the reply only. Input size is limited separately by the model’s context window.
• max_completion_tokens is accepted as an alias. Sending both with different values returns 400 conflicting_parameters.

System instructions

Put instructions in one system message at the start of messages. On the Messages endpoint use the top-level system field instead.

Syntic places a short identity instruction ahead of your text. Your instructions follow it unchanged and take priority for everything the identity instruction does not cover. A second system message later in the conversation is treated as a system note at that point, which is useful for switching mode mid-conversation.

stop

One string or a list of up to four. When the model produces any of them, generation ends before that string, and the string itself is not included in the reply.

When a stop string ends the reply, the response says which one:

{
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Q1 revenue: 4.2M" },
    "finish_reason": "stop_sequence",
    "stop_sequence": "\n\n"
  }]
}

In a stream, the final chunk carries finish_reason: "stop_sequence" and stop_sequence. Text after the match is never sent, even in streaming mode, so a stop string can be relied on as a hard boundary.

user and metadata

user is a stable, opaque id for the person behind the request: a hashed account id, not an email address. Syntic uses it to trace abuse to one end user instead of blocking your whole key.

metadata holds your own tags. Syntic stores it with the usage record so you can filter usage reports by it.

Neither field is sent to the model, and neither affects the reply.

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,
    "max_tokens": 200,
    "stop": ["\n\n", "END"],
    "user": "u_8f31c2",
    "metadata": { "feature": "invoice-summary", "tenant": "acme" },
    "messages": [
      { "role": "system", "content": "Summarise the invoice in one line. Write END when done." },
      { "role": "user", "content": "Invoice 4471: 12 x lavender 2L at 6.50, delivery 9.00." }
    ]
  }'

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,
    max_tokens: 200,
    stop: ['\n\n', 'END'],
    user: 'u_8f31c2',
    metadata: { feature: 'invoice-summary', tenant: 'acme' },
    messages: [
      { role: 'system', content: 'Summarise the invoice in one line. Write END when done.' },
      { role: 'user', content: 'Invoice 4471: 12 x lavender 2L at 6.50, delivery 9.00.' },
    ],
  }),
})
const data = await resp.json()
if (!resp.ok) throw new Error(`${data.error.code}: ${data.error.message}`)
const choice = data.choices[0]
console.log(choice.message.content, choice.finish_reason, choice.stop_sequence)

import os, requests
 
resp = requests.post(
    "https://app.syntic.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}"},
    json={
        "model": "Amara S1.2",
        "stream": False,
        "max_tokens": 200,
        "stop": ["\n\n", "END"],
        "user": "u_8f31c2",
        "metadata": {"feature": "invoice-summary", "tenant": "acme"},
        "messages": [
            {"role": "system", "content": "Summarise the invoice in one line. Write END when done."},
            {"role": "user", "content": "Invoice 4471: 12 x lavender 2L at 6.50, delivery 9.00."},
        ],
    },
    timeout=60,
)
data = resp.json()
resp.raise_for_status()
choice = data["choices"][0]
print(choice["message"]["content"], choice["finish_reason"], choice.get("stop_sequence"))

Errors

All errors use the unified envelope {error:{type, code, message, param}, request_id}.

Build notes for the platform team

• Forward stop in callUpstream(); if the upstream cannot stop on a string, cut the text server-side and still report stop_sequence.
• In streaming mode hold back up to 63 characters at the tail so a partial match is never sent.
• Store user and metadata on the usage row; index metadata.end_user_id.

Related

• Sampling
• Stop reasons
• Chat completions