Streaming

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.

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))
}

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))
}

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)

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.

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 and read the result when it is ready.

Get started

Build

Test

Operate

Integrate

Enabling the stream

What each chunk contains

When not to stream

​Enabling the stream

​What each chunk contains

​When not to stream

Enabling the stream

What each chunk contains

When not to stream