API reference

Celeris implements the OpenAI chat-completions wire format. For usage examples and parameter guidance, see Making requests.

Base URL

https://inference.celeris.ai/<model>/v1

Placeholder	Values today
model	celeris-1

The model request-body field must match the <model> path segment.

Authentication

All endpoints require a bearer key (details):

Authorization: Bearer ck_...

POST /chat/completions

Create a chat completion. Responses can return as one JSON body or as an SSE stream (details).

Request body

Field	Type	Required	Notes
model	string	yes	Must equal the model in the URL path, e.g. celeris-1.
messages	array	yes	OpenAI message objects (role ∈ system | user | assistant | tool). content is a string, or an array of content parts: {"type": "text", "text": ...} and {"type": "image_url", "image_url": {"url": "data:<media-type>;base64,..."}}. Attach as many image_url parts as you need, using inline data: URLs only; see Image input. Prompt tokens plus the requested output budget must be at most 131,072.
max_tokens	integer	recommended	Requested completion-token budget. Any positive integer, and prompt tokens plus the requested budget must be at most 131,072. Defaults to 2048 when neither output-budget field is supplied. A zero or negative value, or a value that would exceed the context window, is rejected. Size it for the expected response; see parameter guidance and output-budget exceptions.
max_completion_tokens	integer	no	Alternative to max_tokens, with the same validation and output-budget behavior. When both fields are supplied, max_completion_tokens sets the budget; send only one.
temperature	number	no	0 recommended for structured tasks.
top_p	number	no	Standard nucleus sampling.
seed	integer	no	Reproducible sampling when combined with temperature: 0.
stop	string | array	no	Stop sequences.
n	integer	no	Number of choices.
tools	array	no	Function/tool definitions in the OpenAI tools schema. When the model calls one, the reply's message.tool_calls carries the function name and JSON arguments, and finish_reason is tool_calls. Send the result back as a tool message to continue.
tool_choice	string | object	no	auto (the default, where the model decides), none (never call), required (directs the model to call one of tools), or {"type": "function", "function": {"name": "..."}} to direct a specific function. required and named forcing apply to non-streaming requests; confirm the reply carries tool_calls. See Tool calling.
response_format	object	no	Constrain non-streaming /chat/completions output to JSON: {"type": "json_object"}, or {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}}} to validate against a schema. See JSON mode.
chat_template_kwargs	object	no	Template controls. {"enable_thinking": true} makes the model reason before answering and false makes it answer directly. The default depends on the model. Where the reasoning is separated it is returned on message.reasoning, apart from message.content. See Reasoning.
reasoning_effort	string	no	Top-level reasoning control. Values and behavior depend on the model; see Reasoning.
include_reasoning	boolean	no	Chat-only (the Responses API has no equivalent). Defaults to true; set false and the reasoning field comes back null instead of carrying the working. It does not suppress a working that was not separated for that request. See Reasoning for the response shape and the post-tool-result exception.
presence_penalty, frequency_penalty	number	no	Standard penalties.
stream	boolean	no	Set true for SSE chunks.
stream_options.include_usage	boolean	no	With streaming, set true to receive the final exact-usage block.

When an output budget is explicitly supplied, the effective input limit is 131,072 minus the requested output budget. Requests over the token limit return 400; request bodies over the endpoint's 64 MiB byte limit return 413.

Response body

{
  "id": "chatcmpl-9f2e41c0",
  "object": "chat.completion",
  "created": 1751673600,
  "model": "celeris-1",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Positive"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1024,
    "completion_tokens": 32,
    "total_tokens": 1056,
    "prompt_tokens_details": {"cached_tokens": 768}
  }
}

finish_reason is stop (natural completion or stop sequence) or length (generation reached its output budget).

When the request enables thinking (chat_template_kwargs: {"enable_thinking": true}), message may also carry a reasoning string alongside content; while streaming it arrives as delta.reasoning chunks ahead of delta.content. Reasoning tokens count as completion tokens in usage. See Reasoning for when it is present and how to detect it.

Token usage

usage reports total input and output token processing for the request. Input processed more than once is counted each time, so reported input usage can exceed the submitted prompt's token count. Output usage includes all output tokens processed for the request, including tokens not returned in the answer. Chat completions report these totals as prompt_tokens and completion_tokens; the Responses API uses input_tokens and output_tokens.

Billing uses the reported usage totals. prompt_tokens_details.cached_tokens is the cached subset of prompt_tokens, charged at the cached-input rate. Uncached input is prompt_tokens - prompt_tokens_details.cached_tokens. Apply the token rates to uncached input, cached input, and output tokens.

The legacy text-completions endpoint, POST /completions, uses the same usage shape. Its prompt_tokens_details.cached_tokens value is likewise part of prompt_tokens and uses the cached input token rate.

POST /v1/responses

Create a model response with the OpenAI Responses API, an alternative to /chat/completions that takes a single input instead of a messages array. It returns one JSON body or an SSE stream (details) and reports token usage. Each request is self-contained: send the full input on every call.

Request body

Field	Type	Required	Notes
model	string	yes	Must equal the model in the URL path, e.g. celeris-1.
input	string | array	yes	A prompt string, or an array of OpenAI input messages (role ∈ system | user | assistant). A message's content is a string, or an array of input parts: {"type": "input_text", "text": ...} and {"type": "input_image", "image_url": "data:<media-type>;base64,...", "detail": "auto"}. The chat text / image_url spellings are rejected here, and detail is required; attach as many input_image parts as you need. See Image input.
instructions	string	no	System-level guidance applied ahead of input.
max_output_tokens	integer	no	Requested output-token budget; any positive integer, bounded by the 131,072-token context window, with the same rejection rules as max_tokens above, but not its 2048 default. When omitted, Responses uses the context window remaining after the rendered input; set it explicitly for the expected response size. See output budgets for exceptions.
temperature	number	no	0 recommended for structured tasks.
top_p	number	no	Standard nucleus sampling.
chat_template_kwargs	object	no	{"enable_thinking": true} makes the model reason before answering and false makes it answer directly. The default depends on the model. Where the reasoning is separated it is returned as an output item of type: "reasoning", ahead of the message item. See Reasoning.
stream	boolean	no	Set true for Responses SSE events.

Response body

{
  "id": "resp_9f2e41c0",
  "object": "response",
  "created_at": 1751673600,
  "status": "completed",
  "model": "celeris-1",
  "output": [
    {
      "id": "msg_1a2b3c4d",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Positive", "annotations": []}]
    }
  ],
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 32,
    "total_tokens": 1056,
    "input_tokens_details": {"cached_tokens": 768}
  }
}

input_tokens_details.cached_tokens is the cached subset of input_tokens. Input, cached input, and output use the same token rates as chat and text completions. See Token usage for how reported usage determines billing.

The generated text is at the type: "message" item's content[0].text (the OpenAI SDK also exposes it as response.output_text). When thinking is enabled and the reasoning is separated, an output item of type: "reasoning" precedes that message item; take the answer from the message item, never the reasoning. See Reasoning on the Responses API for that item's shape and how to detect it. When streaming, the event sequence ends with a response.completed event.

POST /v1/decisions

Ask celeris-1-decision predicate, choice, and score questions using the OpenAI Decisions API format. Send input and an ordered questions list; the response returns answers in the same order. This endpoint exists only under the celeris-1-decision base URL. See OpenAI Decisions API for cURL and OpenAI SDK examples.

POST /v1/systemone

Ask celeris-1-decision typed questions and get probabilities back. This endpoint exists only under the celeris-1-decision base URL. See System One API for cURL and Jev SDK examples.

GET /v1/models

Lists the model served at this base URL, in the standard OpenAI list shape:

curl https://inference.celeris.ai/celeris-1/v1/models \
  -H "Authorization: Bearer $CELERIS_API_KEY"

Retrieve a single model by id with GET /v1/models/celeris-1 to get that model's metadata in the standard OpenAI object shape:

curl https://inference.celeris.ai/celeris-1/v1/models/celeris-1 \
  -H "Authorization: Bearer $CELERIS_API_KEY"

Request headers

Header	Meaning
Authorization	Required on every call: Bearer ck_... (details).
Content-Type	application/json on POST.
X-Client-Trace-Id	Optional caller-supplied trace ID. Echoed on responses so you can correlate failures with application logs and support cases.

Response headers

Header	Meaning
Server-Timing	Service processing duration until the response headers are ready, in milliseconds. For streaming this precedes the first token. See Measuring latency.
X-Client-Trace-Id	Your request's trace id, echoed back if you sent one.
Access-Control-Allow-Origin: *	Browser calls are supported from any origin (details).
Access-Control-Expose-Headers	Lets browser code read Server-Timing and the trace-id headers cross-origin.
Retry-After	On 429: seconds to wait before retrying.

Errors

See Errors for causes, response bodies, and handling guidance. API errors use {"error": {message, type, code}}; use error.code when a status has more than one possible cause.

Status	error.code	Reference
400	Varies by validation error	400 Bad Request
401	invalid_api_key	401 Unauthorized
402	insufficient_quota	402 Payment Required
404	not_found	404 Not Found
413	payload_too_large	413 Payload Too Large
422	None	422 Unprocessable Entity
429	rate_limit_exceeded / service_busy	429 Too Many Requests
502	upstream_error	502 Bad Gateway
503	service_unavailable	503 Service Unavailable