Create chat completion

POST /v1/chat/completions

Creates a model response for the given chat conversation. OpenAI Chat Completions compatible.

When stream is false (the default), the response is a single JSON chat.completion object (application/json).

When stream is true, the response is a text/event-stream of server-sent events. Each event’s data: field carries one chat.completion.chunk JSON object. The stream is terminated by a final data: [DONE] sentinel, which is a literal marker and not valid JSON.

Unsupported or unknown request fields are passed through to the upstream inference endpoint unchanged (they are not rejected by the gateway).

The gateway is a drop-in replacement for OpenAI’s Chat Completions API: point any OpenAI SDK at the gateway’s base URL and use your Springboards API key.

Request body

Content type: application/json

Field	Type	Required	Description
`model`	string	Yes	ID of the model to use (alias or dated version).
`messages`	array of object	Yes	The conversation so far, as a list of messages.
`chat_template_kwargs`	object	No	Springboards extension: key/value pairs forwarded to the upstream model’s chat template. See x-springboards-chat-template-kwargs.
`frequency_penalty`	number	No	Penalty between -2 and 2 for tokens based on their frequency so far.
`max_completion_tokens`	integer	No	Upper bound on the number of tokens generated for the completion.
`max_tokens`	integer	No	Deprecated. Maximum number of tokens to generate. Superseded by max_completion_tokens.
`n`	integer	No	Number of completions to generate for each prompt.
`presence_penalty`	number	No	Penalty between -2 and 2 for tokens based on whether they appear so far.
`seed`	integer	No	Best-effort deterministic sampling seed.
`stop`	array of string	No	Up to 4 sequences where the API stops generating further tokens.
`stream`	boolean	No	If true, partial deltas are streamed as server-sent events terminated by a [DONE] sentinel.
`temperature`	number	No	Sampling temperature between 0 and 2.
`top_p`	number	No	Nucleus sampling probability mass.
`user`	string	No	Stable identifier for the end user, for abuse monitoring.

messages[]

Field	Type	Required	Description
`role`	string (`system`, `user`, `assistant`, `tool`)	Yes	The role of the message author.
`content`	string	Yes	The contents of the message.
`name`	string	No	Optional name to disambiguate participants with the same role.

Fields not listed above are accepted and passed through to the upstream model unchanged.

Responses

`200`

A chat completion. Returned as a single JSON object, or as an SSE stream when stream=true.

Content type: application/json

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the completion.
`object`	string	Yes	The object type, always “chat.completion”.
`created`	integer	Yes	Unix timestamp (seconds) of when the completion was created.
`model`	string	Yes	The model used for the completion.
`choices`	array of object	Yes	The list of completion choices.
`usage`	object	No	Token usage statistics for the request.

choices[]

Field	Type	Required	Description
`index`	integer	Yes	The index of this choice in the list.
`message`	object	Yes	The generated message.
`finish_reason`	string (`stop`, `length`, `content_filter`, `tool_calls`)	Yes	Why generation stopped.

choices[].message

Field	Type	Required	Description
`role`	string	Yes	The role of the author, always “assistant”.
`content`	string	Yes	The contents of the message.

usage

Field	Type	Required	Description
`prompt_tokens`	integer	Yes	Tokens in the prompt.
`completion_tokens`	integer	Yes	Tokens in the generated completion.
`total_tokens`	integer	Yes	Total tokens used (prompt + completion).

Streaming (`text/event-stream`)

Each server-sent event is a bare data: line carrying one JSON payload. The stream is terminated by a final data: [DONE] sentinel — a literal marker, not JSON:

data: {"id":"chatcmpl-123","object":"chat.completion.chunk",...}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk",...}

data: [DONE]

Event payload:

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the completion; shared across all chunks.
`object`	string	Yes	The object type, always “chat.completion.chunk”.
`created`	integer	Yes	Unix timestamp (seconds) of when the completion was created.
`model`	string	Yes	The model used for the completion.
`choices`	array of object	Yes	The list of streamed choice deltas.

choices[]

Field	Type	Required	Description
`index`	integer	Yes	The index of this choice in the list.
`delta`	object	Yes	The incremental message content for this chunk.
`finish_reason`	string (`stop`, `length`, `content_filter`, `tool_calls`)	Yes	Why generation stopped, or null while streaming.

choices[].delta

Field	Type	Required	Description
`content`	string	No	The token(s) appended by this chunk.
`role`	string	No	Present on the first chunk of a choice.

`400`

The request body was malformed or missing the required model field.

`404`

The requested model does not exist.

`502`

The upstream inference endpoint could not be reached.

Examples

Basic request

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $SPRINGBOARDS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flint-alpha",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Streaming

curl -N https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $SPRINGBOARDS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flint-alpha",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://api.example.com/v1",
    api_key=os.environ["SPRINGBOARDS_API_KEY"],
)
completion = client.chat.completions.create(
    model="flint-alpha",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(completion.choices[0].message.content)

Notes

chat_template_kwargs is a Springboards (non-OpenAI) extension. Its key/value pairs are forwarded verbatim to the upstream model’s chat template, allowing per-request template variables that OpenAI’s schema has no field for.