Skip to main content
POST
Create a chat completion

Headers

x-workload
string

The workload the request is for, which ambral/auto serves from its primary model and whose traces record it. A model suffix (ambral/auto:<workload>) names it too, and the two must agree. A request that names none and carries the x-ambral-eval header is for its eval's workload.

x-ambral-upstream
string

The upstream that serves the request, at that upstream's price, for debugging. Otherwise Ambral chooses. A model it doesn't serve is a 400.

Minimum string length: 1
x-ambral-eval
string

<run>; workload=<workload>; model=<model>: the request is a call of an eval run, which Ambral's SDKs set. A request that names no workload (no x-workload, no model suffix) is for the run's. A request for the run's workload is served the run's model, one of the workload's pool, and a request for another workload that workload's primary. Either way it is recorded as an eval trace of the run, never as production. It needs a session, and a value that doesn't parse is a 400.

x-session-id
string

The session the request belongs to: the same id on every request of a session, 8–128 characters of A-Z a-z 0-9 _ -; any other value is ignored. The body's session_id or an x-<vendor>-session-id header names it too. Without one, each request is a session.

x-ambral-end-user
string

Your own id for the person the request serves, recorded on its session's trace: 1–128 characters of A-Z a-z 0-9 . _ : @ + -; any other value is ignored. Without it, the body's safety_identifier, user or metadata.user_id names them. A session keeps the first one it is sent.

x-ambral-labels
string

Labels on the request's session, key=value or a bare tag, comma-separated: up to 16. A key is lowercase letters, digits, ., _ and -, starting with a letter or digit, at most 63 characters. A value is letters, digits, spaces and . _ : / @ + -, at most 128 characters; spaces around it are dropped. A session's labels gather every request's, a later value replacing an earlier one's; once a session holds 16, a later request's new keys are dropped. Invalid labels are ignored, all of them, and the response says why in its own x-ambral-labels header.

Body

application/json
model
string
required
Required string length: 1 - 256
messages
object[]
required
tools
object[] | null
stream
boolean | null
session_id
any

The session the request belongs to, as the x-session-id header names it; a value that isn't a valid session id is ignored.

provider
any

A routing preference: which providers may serve the request, where several could.

cache_control
any

A cache breakpoint after the whole prompt.

{key}
any

Response

The provider's answer: one completion, or a stream of chunks.

The completion, or the error envelope when Ambral couldn't read the provider's answer.

id
string
required
model
string
required
Required string length: 1 - 256
choices
object[]
required
object
string
created
integer
Required range: 0 <= x <= 9007199254740991
system_fingerprint
string | null
service_tier
string | null
usage
object | null