Chat Completions
Use POST /v1/chat/completions when your application already sends ordered message arrays and reads choices[0].message.
On this page 1 of 8
Request#
A minimal request includes a public model and at least one message:
from getpass import getpass
from openai import OpenAI
client = OpenAI(
base_url="https://api.keirolabs.ai/v1",
api_key=getpass("Keiro API key: "),
)
response = client.chat.completions.create(
model="eb1-preview",
messages=[
{"role": "system", "content": "Answer concisely."},
{"role": "user", "content": "Explain vector databases."},
],
)
print(response.choices[0].message.content)
{
"model": "eb1-preview",
"messages": [
{
"role": "user",
"content": "Explain token buckets in one sentence."
}
]
}
Use the system role or supported top-level system compatibility field for stable instructions. Keep application-specific context in explicit messages.
Response#
Read generated text from choices[0].message.content, the terminal reason from choices[0].finish_reason, and canonical token accounting from usage.
Treat the public response layout as the contract. Do not depend on private model selection, vendor metadata, or internal cost fields.
Supported controls#
The current Chat Completions surface supports the documented message input plus controls including stream, temperature, top_p, stop, max_tokens or max_completion_tokens, tools, tool_choice, parallel_tool_calls, response_format, user, metadata, and reasoning controls.
On eb1 models, temperature and top_p apply only when the model serving the request takes them. When it does not, Keiro leaves them out of the call and does not refuse the request.
Strict validation rejects unknown fields with a 400 invalid_request_error whose error.param names the field; see Unsupported request fields. safeguards is accepted and ignored. An integer seed is accepted and ignored: replies are not deterministic. A seed that is not an integer is refused with a 400 whose error.param is seed. n above 1, a non-zero presence_penalty or frequency_penalty, a non-empty logit_bias, logprobs: true and top_logprobs above 0 are refused with a 400 naming the field. The defaults n: 1, presence_penalty: 0, frequency_penalty: 0, logit_bias: {}, logprobs: false and top_logprobs: 0, and null for any of these fields, are accepted and have no effect.
A response_format of type json_schema is accepted. JSON mode, type json_object, is accepted when the model serving the request has it. When the model serving a request cannot honor a schema or JSON mode, the request is refused instead of answered without it; see Structured output conflicts.
store: false, the Chat Completions default, is accepted and has no effect. store: true is refused with a 400 naming store, because the gateway does not offer stored completions.
Audio input and output are not supported. A content part of type input_audio is refused with a 400. modalities and audio are unknown fields here, so they are refused with a 400 naming the field.
service_tier is accepted only as "ultrafast" on eb1-frontier-preview; see Faster frontier requests. Any other value, including auto and default, is refused with a 400 naming service_tier.
metadata holds at most 16 pairs, with keys up to 64 characters and values up to 512 characters. A request over any of these bounds is refused with a 400.
Streaming#
Set stream to true to receive server-sent events. Text arrives in choices[0].delta.content; tool calls arrive in delta.tool_calls. Assemble fragments by choice and tool-call index, and wait for the terminal finish reason before executing a tool. While the model works silently, at any point in the stream, chunks carry one space in delta.reasoning_content; Keiro writes it, and it is not model output. See Chat Completions stream.
from getpass import getpass
from openai import OpenAI
client = OpenAI(
base_url="https://api.keirolabs.ai/v1",
api_key=getpass("Keiro API key: "),
)
stream = client.chat.completions.create(
model="eb1-preview",
messages=[{"role": "user", "content": "Count to three."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
Streams, and long non-streaming requests, live as long as the model keeps working; no wall-clock limit ends them. See Streaming, and the same page for terminal and error handling.
Tools and images#
- Function tools use the Chat Completions nested
tools[].functionshape and returnmessage.tool_calls; see Tool calling. - Images use
image_urlcontent parts inside a user message; see Images and vision.
Faster frontier requests#
Set "service_tier": "ultrafast" with "model": "eb1-frontier-preview" for a faster response. This setting is available on paid self-serve plans and beta and alpha accounts. It is separate from reasoning effort and is unavailable on other models.
When the faster speed is served, it costs $20 per million input tokens, $2 per million cached input tokens, $100 per million output tokens, and $360 per million reasoning tokens. Very long prompts and requests under heavy load can run at standard speed, and those bill at standard rates. The terminal response reports what was served: service_tier is "ultrafast" or "default". In-progress streaming events omit this field.
Ultra frontier requests#
Set "reasoning_effort": "ultra" with "model": "eb1-frontier-preview" to have eb1 orchestration use more models and deeper reasoning on a request. It is opt-in on each request: max does not turn it on, and the other eb1 models ignore ultra. It is available on paid self-serve plans and on alpha, beta and enterprise accounts; on any other account the request runs as a normal request. Compare it with a normal request on your own prompts before relying on it.
It costs more and turns take longer. A request can take many minutes, and a streamed one may send only keepalives before its first text; see Long requests. Billing works as on any eb1 request, and the added models and reasoning appear as reasoning tokens; see Usage and billing. The request also holds more of your spend limit while it runs. A small max_completion_tokens lowers the reasoning depth, so leave it unset for the deepest reasoning. Some tool requests, including those that use provider-hosted tools or remote MCP servers, use one model at the deepest reasoning.
The x-keiro-reasoning-mode response header reports the mode the request ran in: ultra, or standard when it ran as a normal request at normal cost.