Skip to content
EnglishENPortuguêsPT
Try chatGet API key

Create a chat completion

POST
/chat/completions
curl --request POST \
  --url https://api.bayle.ai/chat/completions \
  --header 'Accept-Language: pt-BR' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "model": "qwen3-5-35b-a3b", "messages": [ { "role": "system", "content": "You are a concise geography assistant. Answer in one sentence." }, { "role": "user", "content": "What is the capital of France?" } ], "temperature": 0.7, "max_tokens": 30, "top_p": 0.9, "stop": [ "\n\n" ], "reasoning_effort": "none", "stream": false }'

Generates a chat completion from a list of messages. model and messages are required; temperature, max_tokens, top_p, stop, reasoning_effort, and stream are optional. Function calling through tools and tool_choice is supported, as is vision, by sending image_url content parts inside a message, and document context — a document, presentation, spreadsheet, e-book, plain text, Markdown, CSV, JSON, or source-code file — by sending file content parts. Set stream to true to receive the completion as server-sent events instead of a single JSON body.

Fields Bayle does not name below are forwarded as sent, so a parameter your model supports that this document has not caught up with still reaches it.

Bayle adds no system message and no other instructions to your request: the model sees only the messages you send. To give the model instructions, send your own system message.

To control how much a reasoning model thinks before it answers, set reasoning_effort to one of none, minimal, low, medium, high, xhigh, or max. Higher levels think longer and use more of the output budget. GET /models publishes, for each model, the levels it lists as reasoningEffortOptions and the level it uses when you leave the field out as defaultReasoningEffort, both under model_spec.capabilities. Many models default to low, but not all: some default to medium, high, xhigh, or max, so check the model you call. A model whose supportsReasoningEffort is false does not take a level and may still think before it answers; a level sent to it is accepted, and Bayle does not promise it changes anything.

With none, the model does not show its thinking: reasoning_content is null. A level a model does not list is accepted rather than rejected, and the request still runs; this is observed behaviour, not a guarantee, so rely on reasoningEffortOptions for the levels a model is meant to take. A value outside the seven levels is rejected with 400 and the invalid_request code.

Thinking counts toward max_tokens. A small limit can be spent entirely on thinking, so the response ends with an empty content and a finish_reason of length. Leave room for the answer, or lower the level. When you stream, the thinking arrives first, as its own text in delta.reasoning_content, before any text in delta.content.

A completion that is not streamed must finish within 30 seconds. A long thinking run at a high level on a slower model can take longer, and is then reported as 502 with the api_error type. Send such requests with stream set to true: a streamed response can run for up to 60 minutes.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Accept-Language
string
Example
pt-BR

Chooses the language of any error message in this request’s response. A tag beginning with the two letters pt, in any case, selects Brazilian Portuguese; anything else, including an absent header, selects English. The tag may appear anywhere in a multi-tag header, for example fr-FR;q=0.9,pt;q=0.5,en;q=0.3. Quality values are accepted but ignored, since this is a presence check rather than weighted negotiation.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

The chat completion request. Any field not listed here is forwarded as sent.

object
model
required

The text model to use, as returned by GET /models.

string
messages
required

The conversation so far, oldest message first.

Array<object>
object
role
required
string
Allowed values: system user assistant tool
content
One of:
string
key
additional properties
any
temperature

Sampling temperature. Higher values produce more varied output.

number
max_tokens

Upper bound on the number of tokens generated. For a reasoning model, the thinking counts toward this limit.

integer
top_p

Nucleus sampling threshold.

number
reasoning_effort

How much the model thinks before it answers. Leave it out to get the model’s own default, published per model in GET /models as defaultReasoningEffort, next to the levels it lists in reasoningEffortOptions. A level the model does not list is accepted; a value outside the seven levels is rejected. Thinking counts toward max_tokens. See the operation description.

string
Allowed values: none minimal low medium high xhigh max
stop
One of:
string
stream

When true, the response is a text/event-stream rather than a single JSON body. See the streaming section of the 200 response below.

boolean
tools

Tools the model may call. A function tool has the shape {"type": "function", "function": {"name": "...", "description": "...", "parameters": { /* JSON Schema */ }}}. Built-in tools are given by type alone, for example {"type": "web_search"}.

Array<object>
object
type
required
string
id
string
function
object
name
required
string
description
string
parameters
object
key
additional properties
any
strict
boolean
key
additional properties
any
key
additional properties
any
tool_choice
One of:
string
Allowed values: auto required
key
additional properties
any
Examples

Basic completion with every sampling option

{
  "model": "qwen3-5-35b-a3b",
  "messages": [
    {
      "role": "system",
      "content": "You are a concise geography assistant. Answer in one sentence."
    },
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 30,
  "top_p": 0.9,
  "stop": [
    "\n\n"
  ],
  "reasoning_effort": "none",
  "stream": false
}

Responses

Section titled “Responses”

200

Section titled “200”

The completion. When the request set stream to true this is a text/event-stream; otherwise it is a single JSON body.

object
id
string
object
string
created
integer
model
string
choices
Array<object>
object
index
integer
message
object
role
string
content
string
nullable
reasoning_content

The model’s thinking, for a reasoning model. Null when reasoning_effort is none.

string
nullable
tool_calls

The tools the model asks to call, when it calls any. Send each result back as a tool message carrying the call’s id as tool_call_id.

Array<object>
object
id
string
type
string
function
object
name
string
arguments

The call’s arguments, as a JSON string.

string
key
additional properties
any
key
additional properties
any
key
additional properties
any
finish_reason

Why generation stopped: stop, length when max_tokens ran out, or tool_calls.

string
nullable
key
additional properties
any
usage
object
prompt_tokens
integer
completion_tokens
integer
total_tokens
integer
prompt_tokens_details

Present for some models.

object
cached_tokens
integer
key
additional properties
any
completion_tokens_details

Present for some models.

object
reasoning_tokens

How many of the completion tokens were thinking.

integer
key
additional properties
any
key
additional properties
any
cost

What the request cost, broken out by the balance it was drawn from.

object
usd
number
diem
number
key
additional properties
any
service_tier

The service tier that served the request.

string
nullable
key
additional properties
any
Examples

Basic completion

{
  "id": "chatcmpl-2cf2eb3069810852daeb1629601c1790",
  "object": "chat.completion",
  "created": 1793364272,
  "model": "qwen3-5-35b-a3b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris.",
        "refusal": null,
        "annotations": null,
        "audio": null,
        "function_call": null,
        "reasoning_content": null,
        "reasoning_encrypted": false
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": null,
      "token_ids": null,
      "routed_experts": null
    }
  ],
  "service_tier": null,
  "usage": {
    "prompt_tokens": 36,
    "completion_tokens": 8,
    "total_tokens": 44,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  },
  "prompt_logprobs": null,
  "prompt_token_ids": null,
  "prompt_text": null,
  "kv_transfer_params": null,
  "ec_transfer_params": null,
  "metrics": null,
  "cost": {
    "usd": 0.0000134,
    "diem": 0
  }
}

Headers

Section titled “Headers”
Content-Language
string
Allowed values: en pt-BR

Confirms which of the two supported locales, en or pt-BR, this response was rendered in, so a caller can detect it without reading the message text. Present on every response, success and error alike. On a chat completions stream it is committed together with the initial 200, so it appears whichever way the stream ends.

401

Section titled “401”

No credential was supplied, or the credential supplied is not valid. The request is rejected before any generation work begins. The body uses the shared error envelope, rendered in the negotiated locale.

Media typeapplication/json

Bayle’s OpenAI-shaped error envelope, shared by every error response this API returns.

object
error
required
object
message
required

A human-readable description of the failure, in the negotiated locale. See the Accept-Language request parameter for how that locale is chosen, and the Content-Language response header for which one was served.

string
type
required

OpenAI’s error type vocabulary, for example api_error, authentication_error, invalid_request_error, or rate_limit_error, matching the class of failure so an OpenAI SDK’s exception mapping keeps working.

string
param
required

The request field the failure names, when it names one. Null when the failure is not field-specific, as with authentication or rate limiting.

string
nullable
code
required

Bayle’s semantic error code, reusing OpenAI’s vocabulary where an equivalent exists, for example invalid_api_key or rate_limit_exceeded. Null when Bayle could not identify the specific failure; the envelope is still valid and carries a generic message. The full list lives in Bayle’s error reference rather than being enumerated here.

string
nullable
Examples

English (default)

{
  "error": {
    "message": "Your Bayle API key is missing or could not be verified.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Headers

Section titled “Headers”
Content-Language
string
Allowed values: en pt-BR

Confirms which of the two supported locales, en or pt-BR, this response was rendered in, so a caller can detect it without reading the message text. Present on every response, success and error alike. On a chat completions stream it is committed together with the initial 200, so it appears whichever way the stream ends.

default

Section titled “default”

The request failed before the response began. See the shared error envelope. For a streaming request, a failure after the stream has already started does not use this shape at all: it arrives as an event inside the stream, described under the text/event-stream schema above.

Media typeapplication/json

Bayle’s OpenAI-shaped error envelope, shared by every error response this API returns.

object
error
required
object
message
required

A human-readable description of the failure, in the negotiated locale. See the Accept-Language request parameter for how that locale is chosen, and the Content-Language response header for which one was served.

string
type
required

OpenAI’s error type vocabulary, for example api_error, authentication_error, invalid_request_error, or rate_limit_error, matching the class of failure so an OpenAI SDK’s exception mapping keeps working.

string
param
required

The request field the failure names, when it names one. Null when the failure is not field-specific, as with authentication or rate limiting.

string
nullable
code
required

Bayle’s semantic error code, reusing OpenAI’s vocabulary where an equivalent exists, for example invalid_api_key or rate_limit_exceeded. Null when Bayle could not identify the specific failure; the envelope is still valid and carries a generic message. The full list lives in Bayle’s error reference rather than being enumerated here.

string
nullable
Examples

400: an invalid parameter, such as an unknown `reasoning_effort` level or no `messages`

{
  "error": {
    "message": "Bayle could not process this request because one or more parameters are invalid.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}

Headers

Section titled “Headers”
Content-Language
string
Allowed values: en pt-BR

Confirms which of the two supported locales, en or pt-BR, this response was rendered in, so a caller can detect it without reading the message text. Present on every response, success and error alike. On a chat completions stream it is committed together with the initial 200, so it appears whichever way the stream ends.