Skip to content
Appmake
Kalle API docs

Streaming

Set stream to true and Kalle sends the answer while it writes it, as server-sent events. People see the first words almost at once instead of waiting for the whole answer.

curl -N https://api.kalle.build/v1/messages \
  -H "Authorization: Bearer $KALLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kalle-turbo",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "Write a short welcome email for new members of a climbing gym."
      }
    ]
  }'

What the stream looks like

Every event has an event: line and a data: line with JSON. The JSON always has a type, so you can ignore the event: lines if your client makes that easier.

Text
event: message.start
data: {"type":"message.start","message":{"id":"msg_01J8Z6","model":"kalle-turbo"}}

event: text.delta
data: {"type":"text.delta","index":0,"text":"Welcome to the wall"}

event: text.delta
data: {"type":"text.delta","index":0,"text":", Maja! Your first session"}

event: message.done
data: {"type":"message.done","stop_reason":"end_turn","usage":{"input_tokens":24,"output_tokens":186}}

Event types

EventWhen it arrivesData
message.startOnce, first.message.id and message.model.
text.deltaMany times.index of the content block and the next piece of text.
tool_useWhen Kalle calls a tool.The complete call: id, name and input.
message.doneOnce, last.stop_reason and the final usage.
pingNow and then.Nothing. Keeps the connection open through proxies.
errorIf something fails mid-stream.An error object, as described in Errors.

Join the text of every text.delta with the same index to get the full text block. tool_use arrives whole, so you never have to stitch together half a JSON object.

Errors during a stream

The HTTP status is sent before the first event, so a bad request or an invalid key still fails with a normal error response. Once the stream has started, problems arrive as an error event and the stream ends.

Streaming through your own server

Your API key must stay on your server, so stream from Kalle to your server and on to the browser. Most frameworks can return the response body as a stream. Forward the events as they arrive and do not buffer the whole answer first.