Skip to main content
POST
Create a chat completion

Authorizations

Authorization
string
header
required

A workspace API key in an Authorization: Bearer header. A missing header, a scheme other than Bearer, a key of the wrong shape, and a key we reject are all 401.

Body

application/json

An OpenAI chat completion request. Fields beyond the ones named here are forwarded to the provider unchanged rather than refused for being unfamiliar.

model
string
required

The model to call, which the live catalog has to offer for the responses family. A provider-pinned id, {provider}/{that provider's own id}, is split once on the first slash. A routing-profile slug, profile/{identifier}, tries that profile's models in your own order. unirouter/auto, or its second spelling hopscotch/auto, names whichever route your workspace made its default. A bare model id is refused with 400 and the code model_id_not_pinned. GET /v1/models lists the exact strings this key can call.

Example:

"openai/gpt-4o-mini"

messages
object[]
required
max_tokens
integer

The most output tokens the reply may use. Optional, as it is on OpenAI. Left out, it is filled in for the providers whose own API refuses a request that does not carry one, and the figure used is the model's published max_output_tokens, which GET /v1/models/{model} reports and which is what credit is held for on a request naming no ceiling. Every other provider is sent the request unchanged. max_completion_tokens counts as this field being given.

Example:

256

stream
boolean

Response

The completion. A response that is not streamed carries the provider's token counts in its own usage object. Its model field echoes the slug you asked for rather than the provider's internal name, except in three cases that are returned as the provider sent them: a streamed reply, whose frames are passed through unchanged; a request naming a routing profile, which names a chain rather than one model; and a successful body carrying no string model field at all.

When stream is true the body is text/event-stream instead, and the counts arrive on a :x-hopscotch-usage comment line immediately before data: [DONE]; the server-sent events specification requires parsers to ignore comment lines, so an SDK never sees it.

An OpenAI chat completion, as the provider produced it.

id
string
object
string
Example:

"chat.completion"

created
integer
model
string
choices
object[]
usage
object