Streaming

Set stream: true to receive the response incrementally instead of waiting for the whole completion. Streaming lets you show text as soon as the model produces it.

curl https://api.reflection.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer $REFLECTION_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "Beam-501B-A23B",
    "messages": [{"role": "user", "content": "Why is the sky blue?"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.reflection.ai/openai/v1",
    api_key=os.environ["REFLECTION_API_KEY"],
)

stream = client.chat.completions.create(
    model="Beam-501B-A23B",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices:
        delta = chunk.choices[0].delta
        if delta.content:
            print(delta.content, end="", flush=True)
    if chunk.usage:
        print(f"\n\nTotal tokens: {chunk.usage.total_tokens}")

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.reflection.ai/openai/v1",
  apiKey: process.env.REFLECTION_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "Beam-501B-A23B",
  messages: [{ role: "user", content: "Why is the sky blue?" }],
  stream: true,
  stream_options: { include_usage: true },
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) process.stdout.write(content);
  if (chunk.usage) console.log(`\n\nTotal tokens: ${chunk.usage.total_tokens}`);
}

Event format

The response is a stream of server-sent events with content type text/event-stream. Each event is a data: line carrying a JSON chat completion chunk, and a completed stream ends with data: [DONE]:

data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}],"created":1791198000,"model":"Beam-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"wGMmHWX0D2a"}

data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{"reasoning_content":"The user wants a one-sentence explanation of Rayleigh scattering."},"finish_reason":null}],"created":1791198000,"model":"Beam-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"lCav4U"}

data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{"content":"Air molecules scatter short blue wavelengths of sunlight far more"},"finish_reason":null}],"created":1791198000,"model":"Beam-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"cVmEhIa5zitBUV3O"}

data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{"content":" than longer red ones, so blue light reaches your eyes from every"},"finish_reason":null}],"created":1791198000,"model":"Beam-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"6WhBZTNBLlolaThi"}

data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{"content":" part of the sky."},"finish_reason":null}],"created":1791198000,"model":"Beam-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"cGv4yGc4Dx-S3LMCyfoevWzBWsxtzk7cCIthcSCHxpJ4yLTophhyxeC6O2Fas9Q-"}

data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"created":1791198000,"model":"Beam-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"kxtEv0FWmRsjv6IHiQoowTE2U-ZgKvc_EmkfM2CwbV3xz_mxCobC3dFUgFzknbzBzZunVlqbQG1jCUa4YFxVcRtdghX"}

data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[],"created":1791198000,"model":"Beam-501B-A23B","object":"chat.completion.chunk","usage":{"prompt_tokens":23,"completion_tokens":45,"total_tokens":68,"completion_tokens_details":{"reasoning_tokens":14}},"obfuscation":"QkHVHPHgk3xZMnPQqH_DnJvrzXV"}

data: [DONE]

Every chunk in a stream has the same id and created. Each chunk’s choices[0].delta holds the new part of the message:

Delta field	Contains
`role`	`assistant`, on the first chunk.
`content`	The next piece of the answer.
`reasoning_content`	The next piece of the model’s reasoning, reported separately from `content`.
`tool_calls`	Fragments of tool calls. See Streaming tool calls.

With reasoning enabled, the model’s reasoning streams in delta.reasoning_content before the answer starts in delta.content, so a loop that prints only content can wait silently at first. Read reasoning_content too if you want to show progress; in Python, use getattr(delta, "reasoning_content", None).

finish_reason is null until the final chunk for the choice, which carries the reason generation ended. Concatenate the content values in order to rebuild the full answer.

Token usage

Set stream_options.include_usage to true to receive usage for the whole request. The stream then sends one more chunk before data: [DONE], with usage set and an empty choices array. Guard for the empty array when you read choices[0].

Padding

To protect against side-channel attacks that infer content from traffic, streamed events have their payloads and timings normalized. Each event carries an obfuscation field of random characters that pads it to a fixed length. Ignore the field’s value. Turn padding off with "stream_options": {"include_obfuscation": false} only where traffic can’t be observed, for example on a loopback connection. Doing so may slightly increase the rate at which chunks arrive.

Streaming tool calls

When the model calls a tool in a streamed response, each tool call arrives in fragments across delta.tool_calls. Every fragment has an index identifying the call; the call’s id, type, and function.name arrive first, then pieces of function.arguments. Accumulate the fragments by index and parse arguments as JSON once finish_reason is tool_calls.

Python

tool_calls = {}

for chunk in stream:
    if not chunk.choices:
        continue
    for fragment in chunk.choices[0].delta.tool_calls or []:
        call = tool_calls.setdefault(
            fragment.index, {"id": None, "name": "", "arguments": ""}
        )
        if fragment.id:
            call["id"] = fragment.id
        if fragment.function and fragment.function.name:
            call["name"] += fragment.function.name
        if fragment.function and fragment.function.arguments:
            call["arguments"] += fragment.function.arguments

Handling interruptions

If the connection drops before data: [DONE], the response is incomplete. Treat it as failed and retry the request; the API does not resume partial streams.

Get started

Coding agents

Mirror CLI

Guides

Resources

Event format

Token usage

Padding

Streaming tool calls

Handling interruptions

​Event format

​Token usage

​Padding

​Streaming tool calls

​Handling interruptions

Event format

Token usage

Padding

Streaming tool calls

Handling interruptions