Chat Completions Streaming

~22 min · streaming, chat-completions, delta

Level 0Tokenizer

0 XP0/54 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Set stream=True to receive tokens as they're generated. Each chunk contains a delta object with partial content.

Delta Object Fields

delta.content — Text token(s)
delta.role — Appears in the first chunk only
delta.tool_calls — Tool call fragments (for function calling)
delta.refusal — Refusal message (rare)

The lifecycle, in chunks

The first chunk usually carries delta.role: "assistant" and no content — that's the 'I'm starting' signal. Mid-stream chunks carry delta.content incrementally. The final chunk carries finish_reason and an empty content. Then a literal data: [DONE] line closes the stream.

Tool-calling streams interleave a different shape: delta.tool_calls[i].function.arguments arrives as JSON fragments (not valid JSON individually). Concatenate, then parse at the end — see Function Call Streaming below.

Code

Iterating delta.content·python

stream = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Count from 1 to 5."}],
    stream=True,
    stream_options={"include_usage": True},  # get usage in final chunk
)

full_text = ""
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        delta = chunk.choices[0].delta.content
        full_text += delta
        print(delta, end="", flush=True)
    # Last chunk with usage
    if chunk.usage:
        print(f"\\nTokens: {chunk.usage.total_tokens}")
print(f"\\nFull response: {full_text}")

External links

Stream chunk shape

Exercise

Print every chunk you receive. Note where role appears, where content first becomes non-empty, where finish_reason arrives, and where [DONE] is. Draw the lifecycle on paper.