Docs

Chat completions

POST/api/v1/chat/completions

The main endpoint. Same request and response shape as OpenAI, with exact per-token billing settled from what the engine actually generated.

Request

Field	Default	Notes
model	required	A model id from the catalog. Unknown ids return 404 model_not_found.
messages	required	OpenAI chat format: system / user / assistant turns.
max_tokens	default 1024	Output ceiling. Capped at 32,768 per request; max_completion_tokens works too.
stream	default false	Server-sent events instead of one JSON body. See Streaming.
stream_options	optional	{"include_usage": true} appends a final usage chunk to a stream.
everything else	passthrough	temperature, top_p, stop, seed, response_format… forwarded to the engine untouched.

When you omit max_tokens, the gateway applies a default of 1,024. Long-form generation should set it explicitly; the per-request ceiling is 32,768.

Example

curl https://tokenkiln.com/api/v1/chat/completions \
  -H "Authorization: Bearer tk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Summarize SSE in one sentence."}
    ],
    "max_tokens": 200,
    "temperature": 0.7
  }'

Response

A standard OpenAI chat.completion object, produced by the inference engine and passed through unmodified, including usage with exact token counts.
The x-request-id header identifies the request on your Activity page and in support conversations.
Engine rejections (a prompt over the model's context window, malformed tool schemas) are forwarded verbatim with the engine's status code. You are not charged for them.

How billing works

Before dispatch, the gateway reserves the worst case: estimated prompt tokens plus max_tokens, at the model's per-token rates. A balance that cannot cover the reserve gets 402 insufficient_quota and nothing is sent.
After the response, the reserve is settled against the engine's reported usage. You pay for actual tokens, never the estimate.
Failed requests, upstream errors included, are never billed.

Pricing per model is on the catalog page and in GET /models. Spend controls are covered under Rate limits and caps.