API

Chat completions

POST /v1/chat/completions — the same request and response as the OpenAI Chat Completions API, with both non-streaming and streaming (SSE) support.

Non-streaming#

The response is returned in one piece once the model finishes, with usage (input/output token counts) — these are the tokens you are billed for.

Non-streaming

curl https://<host>/v1/chat/completions \
  -H "Authorization: Bearer sk-kompa-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "Bạn là trợ lý ngắn gọn."},
      {"role": "user", "content": "Giải thích token là gì trong 2 câu."}
    ],
    "max_tokens": 300,
    "temperature": 0.7
  }'

Streaming#

Set stream: true to receive the response incrementally via Server-Sent Events (data: {…}, ending with data: [DONE]). Add stream_options.include_usage if you want the final chunk to include usage; the platform always collects usage for billing whether or not you enable it.

Streaming

curl -N https://<host>/v1/chat/completions \
  -H "Authorization: Bearer sk-kompa-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Viết một bài thơ 4 câu về Hà Nội."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Aborting a stream still bills what was generated

If the client closes the connection, you pay for all of the input and for the output generated up to that point. See Billing.

If the provider fails after the stream has started, the HTTP status is already 200, so you receive an error event like data: {"error": {"message", "type": "api_error", "code": "upstream_error"}} and then the stream closes. Check every chunk for an error field.

Parameters#

All standard OpenAI parameters (temperature, top_p, tools, tool_choice, response_format, stop, seed, …) are forwarded to the model. A few parameters have specific rules:

model
Rule
Required. A model name from the pricing table. Unknown name → 404 model_not_found; embedding model → 400 model_type_mismatch.
messages
Rule
Required. A non-empty array of objects.
max_tokens
Rule
Optional. If omitted, defaults to 4,096 (or the model’s max output if lower). Values above the model’s max output are clamped down. Used to compute the hold (see holds).
max_completion_tokens
Rule
Equivalent to max_tokens (used by reasoning models). Same rules.
n
Rule
Only n = 1 is supported; any other value → 400 unsupported_parameter.
stream
Rule
Boolean. true = SSE.
metadata
Rule
Ignored (not sent to the provider).

Parameters with specific rules
Parameter	Rule
`model`	Required. A model name from the pricing table. Unknown name → `404 model_not_found`; embedding model → `400 model_type_mismatch`.
`messages`	Required. A non-empty array of objects.
`max_tokens`	Optional. If omitted, defaults to 4,096 (or the model’s max output if lower). Values above the model’s max output are clamped down. Used to compute the hold (see holds).
`max_completion_tokens`	Equivalent to `max_tokens` (used by reasoning models). Same rules.
`n`	Only `n = 1` is supported; any other value → `400 unsupported_parameter`.
`stream`	Boolean. `true` = SSE.
`metadata`	Ignored (not sent to the provider).

The maximum body size is 10 MB (413 request_too_large). Images in messages (vision) are supported if the model supports them.

Response#

model is always the model name you called; id is a chatcmpl-… value generated by Any.
usage.prompt_tokens / usage.completion_tokens: the billed token counts (may include a cached-tokens breakdown).
The X-Request-Id header (req_…) is present on every response, including errors. Request history and costs (USD) are in Usage. The dashboard Playground also returns an X-Kompa-Cost-USD header with the cost of the (non-streaming) request.

Retries

The OpenAI SDK retries 429 and 5xx errors automatically. A 402 (out of funds, key spend limit reached) won’t go away on retry — top up or lower max_tokens. See Error codes.