Skip to main content
POST
Create a chat completion

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

Lets you retry safely. Valar records a reservation under the combination of organization, API key, and Idempotency-Key, so sending the same value again hands back the stored response rather than running inference a second time. Values can be up to 255 characters. See Idempotent Requests for the complete rules.

Maximum string length: 255

Body

application/json
model
string
required
messages
object[]
required
Minimum array length: 1
temperature
number | null
Required range: 0 <= x <= 2
top_p
number | null
Required range: 0 <= x <= 1
max_completion_tokens
integer | null
Required range: x >= 1
response_format
object
reasoning_effort
enum<string> | null
Available options:
none,
minimal,
low,
medium,
high,
xhigh
n
enum<integer>

Must be 1; requesting multiple choices is not supported yet.

Available options:
1
modalities
enum<string>[]
Required array length: 1 element
Available options:
text
stream
boolean

Set this to true to receive the answer as a Server-Sent Events stream of chat.completion.chunk objects rather than one JSON payload.

stream_options
object

Settings that only take effect while streaming (stream is true).

store
boolean
default:true

Accepted for compatibility and ignored. Chat Completions carries a model's thinking as ordinary content you resend, so there is nothing for this field to select. It does not control retention. See the Data Processing Addendum for retention commitments.

background
boolean
default:false

Valar extension, the same as background on the Responses API. Set to true to get a handle instead of holding the connection: the call returns 202 with a response object right away, and you poll Fetch a response with its id. Once the run succeeds, that fetch returns the finished chat completion. Cannot be combined with stream.

user
string
Maximum string length: 256
metadata
object

Optional string-valued metadata. Use completion_window to influence scheduling, and completion_webhook together with webhook_token to wire up a webhook that fires on completion.

Response

The chat completion. By default this is one JSON object; with stream: true it becomes a Server-Sent Events stream of chat.completion.chunk objects closed by a final data: [DONE] line.

id
string
required
object
enum<string>
required
Available options:
chat.completion
created
integer
required
model
string
required
choices
object[]
required
Minimum array length: 1
usage
object