> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomask.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming

> Server-sent events with standard chat.completion.chunk objects.

> [!NOTE]
>
> Use a current public model ID from [Models](https://nomask.ai/models) or `GET /models`. Example IDs and options must match the selected model's advertised capabilities and limits.

Set `"stream": true` to receive the completion as server-sent events, token by token, in the standard OpenAI chunk format.

## Enabling streaming

> [tab] Python
>
> ```python theme={"system"}
> stream = client.chat.completions.create(
>     model="nomask-1.2",
>     messages=[{"role": "user", "content": "Write a haiku about the sea."}],
>     stream=True,
>     stream_options={"include_usage": True},
> )
> for chunk in stream:
>     delta = chunk.choices[0].delta if chunk.choices else None
>     if delta and delta.content:
>         print(delta.content, end="", flush=True)
> ```

> [tab] curl
>
> ```bash theme={"system"}
> curl -N https://api.nomask.ai/v1/chat/completions \
>   -H "Authorization: Bearer $NOMASK_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "nomask-1.2",
>     "messages": [{"role": "user", "content": "Write a haiku about the sea."}],
>     "stream": true,
>     "stream_options": {"include_usage": true}
>   }'
> ```

## The chunk stream

The response is `text/event-stream`. Each event is a `chat.completion.chunk` object, and the stream ends with `data: [DONE]`:

```text theme={"system"}
data: {"id":"chatcmpl_...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},"index":0}]}

data: {"id":"chatcmpl_...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Waves"},"index":0}]}

data: {"id":"chatcmpl_...","object":"chat.completion.chunk","choices":[{"delta":{"content":" fold"},"index":0}]}

data: {"id":"chatcmpl_...","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]
```

* Reasoning tokens arrive as `delta.reasoning_content`, interleaved before the answer. See [Reasoning](https://docs.nomask.ai/reasoning.md).

## Usage and cost on streams

Pass `"stream_options": {"include_usage": true}` and the final data chunk before `[DONE]` has an empty `choices` array and carries the totals:

```json theme={"system"}
{
  "object": "chat.completion.chunk",
  "choices": [],
  "usage": {"prompt_tokens": 14, "completion_tokens": 21, "total_tokens": 35},
  "nomask": {
    "model_cost_usd": 0.000049,
    "cost_usd": 0.000049
  }
}
```

`nomask.cost_usd` is the exact USD amount charged to your balance for the request, the same figure `GET /usage` will show.

Confirmed cached input and frozen savings are included in the usage metadata. See [Prompt Caching](https://docs.nomask.ai/prompt-caching.md) for the response fields and billing rules.

## Errors mid-stream

If the model fails after the stream has started, you receive a final chunk containing an `error` object in the standard envelope, then `[DONE]`. Errors before any tokens are sent return a normal JSON error response with the right HTTP status instead.

## Disconnects and billing

Billing settles when the request finishes on the server. If your client disconnects mid-stream, the tokens generated up to that point are still billed; when exact usage is unavailable for an interrupted stream, token counts are estimated and the usage record is flagged with `tokens_estimated: true`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.