StreamingEndpoints

Set stream: true on a chat request to get the answer as server-sent events (text/event-stream). Each event is a chat.completion.chunk, and the stream ends with data: [DONE].

Read the events in order

1. A first chunk with delta.role set to assistant.
2. Content chunks (delta.content) or tool-call chunks (delta.tool_calls).
3. A chunk with finish_reason.
4. A usage chunk: choices is empty, with usage and kaer (request_id, cost_usd, free_credit_usd).
5. data: [DONE]

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1767225600,"model":"x1-kaer","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1767225600,"model":"x1-kaer","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1767225600,"model":"x1-kaer","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1767225600,"model":"x1-kaer","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":9,"total_tokens":21,"prompt_tokens_details":{"cached_tokens":0}},"kaer":{"request_id":"req_…","cost_usd":0.0000048,"free_credit_usd":0.0000048}}

data: [DONE]

Understand how a stream is billed

A stream settles at the cost the model service reports in its usage chunk. If the stream ends before that chunk (you disconnect, or it times out), the gateway charges an estimate from the text sent, about 4 characters per token for prompt and answer, and never more than the hold. Open streams count toward your tier's concurrent stream limit until they end.

Handle timeouts and errors

If the model sends nothing for 90 seconds, or a stream runs past 15 minutes, the gateway sends an error event and closes the stream: data: {"error": {"type": "server_error", "code": "upstream_idle", ...}} (or max_duration), then [DONE]. If the model provider fails partway, you get an error event, a chunk with finish_reason: "error", then the usage chunk. The OpenAI SDKs raise an exception when they read an error event.

Streaming responses carry x-request-id and the rate-limit headers, but not x-kaer-cost-usd: the cost arrives in the usage chunk.

Stream a response

curl -N https://api.kaer.ai/v1/chat/completions \
  -H "Authorization: Bearer $KAER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x1-kaer",
    "messages": [{"role": "user", "content": "Count to 10."}],
    "stream": true
  }'