> ## 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

> Receba a resposta de um Canvas enquanto ela está sendo gerada

Por padrão, uma completion retorna quando a resposta inteira está pronta. Com `stream: true`, a API começa a responder assim que o modelo produz os primeiros tokens, então você pode mostrar progresso a um usuário ou começar a processar mais cedo.

Streaming está disponível com `canvas_id` e `version_id`. Tarefas criadas com `application_id` sempre rodam de forma assíncrona e não usam streaming.

## Habilitando o stream

Acrescente `stream: true` à requisição. Com os SDKs, a completion retornada passa a ser um iterável de 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
    }'
```

## O que cada chunk contém

Cada chunk é um objeto de stream de `chat.completion`. Os campos que você vai usar:

| Campo | Significado |
| - | - |
| `id`, `object`, `created`, `model` | Identificam a completion e o modelo que está respondendo. |
| `choices[].delta.content` | O trecho de texto produzido desde o chunk anterior. Concatene os deltas para reconstruir a resposta. |
| `choices[].delta.role` | O papel da mensagem (`assistant`) quando presente, caso contrário `null`. |
| `choices[].finish_reason` | `null` enquanto o modelo ainda está gerando; um valor quando ele para. |
| `choices[].index` | A posição da escolha. |
| `message` | O objeto de mensagem da resposta de stream: `role`, `content` e `structured_content` quando o Canvas tem um Formato de Saída. |

Use `delta.content` para exibir o texto conforme ele chega, e leia `message.structured_content` quando precisar dos campos do Formato de Saída em vez do texto. O schema completo está em [Run Canvas](https://docs.tela.com/api-reference/completion/create.md).

> [!NOTE]
>
> O formato do stream por HTTP puro (como os chunks são delimitados no corpo da resposta) não está documentado aqui. Os SDKs cuidam disso para você; se você consumir o stream com o seu próprio cliente HTTP, inspecione a resposta bruta antes.

## Quando não usar streaming

O streaming mantém a conexão HTTP aberta durante toda a execução. Para documentos longos processados em segundo plano, ou quando quem chama não precisa da saída parcial, prefira [`async` ou uma `webhook_url`](https://docs.tela.com/pt/completion-api/async-and-webhooks) e leia o resultado quando ele estiver pronto.


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