Stream a chat answer

POST /api/chat/send is the only streaming endpoint. It accepts one student message and responds with text/event-stream. OpenAPI cannot describe the event framing, so this page is the contract.

Request

POST /api/chat/send
Authorization: Bearer <token>
Content-Type: application/json

Field	Type	Rule
`message`	string	Optional. Defaults to `""`. Maximum 8000 characters.
`image.data`	string	Base64 of the image bytes. No `data:` prefix.
`image.mimeType`	string	For example `image/jpeg`.

Send message, image, or both. A request with an empty message and no image returns 400 with {"error":"empty message"}. The 400 arrives before the stream, as normal JSON.

{
  "message": "Bu soruyu çözemedim",
  "image": { "data": "/9j/4AAQSkZJRgABAQ...", "mimeType": "image/jpeg" }
}

The image travels inline as base64 in the JSON body. Compress and resize the photo on the device before you encode it. Base64 adds about 33 percent to the byte count.

Response events

The response status is 200 and the content type is text/event-stream. Each event has a name and a JSON data payload.

ChatChunkEvent

One text delta. Repeats many times.

event: chunk
data: {"text":"Tamam, "}

ChatDoneEvent

Terminal. Holds the complete answer text and the reactions.

event: done
data: {"text":"Tamam, türevden başlayalım.","reactions":[{"emoji":"🎉"}]}

ChatErrorEvent

Terminal. The turn failed.

event: error
data: {"error":"chat failed"}

The stream emits exactly one terminal event: done or error. A model failure is an error event, not an HTTP status. The HTTP status stays 200 in both cases.

Rules for the client

Append each chunk payload to the text on screen.
On done, replace the text on screen with the text field. This corrects any lost delta.
On done, show the emoji in reactions. The array is usually empty. Lala reacts rarely.
On error, show a retry control. Do not show the partial text as a finished answer.
If the socket closes with no terminal event, treat the turn as failed.

The server persists the student message before the model runs. It persists the answer after the model runs. A turn that fails mid-stream can leave the student message in the history with no answer. Call GET /api/chat/history to resynchronize after an error.

No resume

The stream has no message identifier and no cursor. You cannot reconnect to a running turn. If the application goes to the background and the connection drops, the server still completes the turn and writes the answer to the history. Read the history back when the screen returns.

Timing

The server aborts the model call after 60 seconds. One turn can take several model steps, because Lala can call tools. Allow at least 90 seconds of client timeout on this request. Do not set an idle timeout below the gap between two chunks.

Client code

final request = http.Request('POST', Uri.parse('$baseUrl/api/chat/send'))
  ..headers['Authorization'] = 'Bearer $token'
  ..headers['Content-Type'] = 'application/json'
  ..body = jsonEncode({'message': text});

final response = await http.Client().send(request);

String? eventName;
await for (final line in response.stream
    .transform(utf8.decoder)
    .transform(const LineSplitter())) {
  if (line.startsWith('event: ')) {
    eventName = line.substring(7).trim();
  } else if (line.startsWith('data: ')) {
    final payload = jsonDecode(line.substring(6));
    switch (eventName) {
      case 'chunk':
        onChunk(payload['text'] as String);
      case 'done':
        onDone(payload['text'] as String, payload['reactions'] as List);
      case 'error':
        onError(payload['error'] as String);
    }
  }
}

const res = await fetch(`${baseUrl}/api/chat/send`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message: text }),
});

const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = '';
let eventName = null;

for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value;
  const lines = buffer.split('\n');
  buffer = lines.pop();
  for (const line of lines) {
    if (line.startsWith('event: ')) eventName = line.slice(7).trim();
    else if (line.startsWith('data: ')) handle(eventName, JSON.parse(line.slice(6)));
  }
}

curl -N -X POST "$BASE_URL/api/chat/send" \
  -H "Authorization: Bearer $LALA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Merhaba"}'

Do not use the browser EventSource API. EventSource sends only GET requests and cannot set the Authorization header. Use fetch with a stream reader, as shown above.

Concurrency

Send one turn at a time for one student. The server does not reject a second concurrent request, but both turns read and write the same conversation history. Disable the send control until a terminal event arrives.

Start here

Build

Understand

For agents

Request

Response events

Rules for the client

No resume

Timing

Client code

Concurrency

​Request

​Response events

​Rules for the client

​No resume

​Timing

​Client code

​Concurrency

Request

Response events

Rules for the client

No resume

Timing

Client code

Concurrency