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

# Streaming

> Receive the answer of a Canvas while it is being generated

By default a completion returns when the whole answer is ready. With `stream: true` the API starts answering as soon as the model produces the first tokens, so you can show progress to a user or begin processing early.

Streaming is available with `canvas_id` and `version_id`. Tasks created with `application_id` always run asynchronously and do not stream.

## Enabling the stream

Add `stream: true` to the request. With the SDKs, the returned completion becomes an iterable of chunks.

```typescript TypeScript Tela SDK theme={null}
import fs from 'node:fs'
import { createTelaClient } from '@meistrari/tela-sdk-js'
import type { TelaFile } from '@meistrari/tela-sdk-js'

const tela = createTelaClient({
    apiKey: process.env.TELA_API_KEY,
})

const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile(fs.createReadStream('./sample-invoice.pdf')),
    },
    stream: true,
})

for await (const chunk of completion) {
    console.log(JSON.stringify(chunk))
}
```

```javascript JavaScript Tela SDK theme={null}
import fs from 'node:fs'
import { createTelaClient } from '@meistrari/tela-sdk-js'

const tela = createTelaClient({
    apiKey: process.env.TELA_API_KEY,
})

const completion = await tela.completions.create({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile(fs.createReadStream('./sample-invoice.pdf')),
    },
    stream: true,
})

for await (const chunk of completion) {
    console.log(JSON.stringify(chunk))
}
```

```python Python Tela SDK theme={null}
import os
from tela import create_tela_client

client = create_tela_client(
    api_key=os.getenv("TELA_API_KEY"),
)

with open("./sample-invoice.pdf", "rb") as file:
    completion = client.completions.create(
        canvas_id=os.getenv("TELA_CANVAS_ID"),
        variables={
            "document": client.create_file(file),
        },
        stream=True,
    )

    for chunk in completion:
        print(chunk)
```

```sh cURL theme={null}
curl -X POST https://api.tela.com/v2/chat/completions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TELA_API_KEY" \
    -d '{
        "canvas_id": "95cec438-6080-44fe-8275-28b16bd40178",
        "variables": {
            "document": { "file_url": "data:application/pdf;base64,JVBERi0xLjUKJeLjz9MKNCAwIG9ia..." }
        },
        "stream": true
    }'
```

## What each chunk contains

Each chunk is a `chat.completion` stream object. The fields you will use:

| Field | Meaning |
| - | - |
| `id`, `object`, `created`, `model` | Identify the completion and the model answering it. |
| `choices[].delta.content` | The piece of text produced since the previous chunk. Concatenate the deltas to rebuild the answer. |
| `choices[].delta.role` | The role of the message (`assistant`) when present, otherwise `null`. |
| `choices[].finish_reason` | `null` while the model is still generating; a value once it stops. |
| `choices[].index` | The position of the choice. |
| `message` | The message object of the stream response: `role`, `content`, and `structured_content` when the Canvas has an Output Format. |

Use `delta.content` to display text as it arrives, and read `message.structured_content` when you need the fields of the Output Format rather than the text. The full schema is in [Run Canvas](https://docs.tela.com/api-reference/completion/create.md).

> [!NOTE]
>
> The wire format of the stream over plain HTTP (how chunks are delimited in the response body) is not documented here. The SDKs handle it for you; if you consume the stream with your own HTTP client, inspect the raw response first.

## When not to stream

Streaming keeps the HTTP connection open for the whole run. For long documents processed in the background, or when the caller does not need partial output, prefer [`async` or a `webhook_url`](https://docs.tela.com/en/completion-api/async-and-webhooks) and read the result when it is ready.


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