Variáveis e arquivos

Variáveis são as entradas de um Canvas. Na requisição, elas vão no objeto variables, com o nome da variável exatamente como aparece no Canvas. Cada valor é um texto ou um arquivo. O diálogo Conectar via API gera o snippet com as variáveis do Canvas já no lugar, então você só preenche os valores.

Texto

Uma variável de texto recebe uma string simples.

variables: {
    document: 'Document content',
},

variables={
    "document": "Document content",
}

"variables": {
    "document": "Document content"
}

Arquivos

Uma variável de arquivo recebe um objeto com uma file_url. A URL pode apontar para três tipos de conteúdo:

`file_url`	Quando usar
`https://…`	O arquivo já está acessível na internet, como um documento no seu próprio storage.
`data:<mime type>;base64,…`	O arquivo está em memória e é pequeno o bastante para ir inline.
`vault://<id do arquivo>`	Você enviou o arquivo para o Tela antes, com os endpoints de arquivo (veja abaixo).

"variables": {
    "document": {
        "file_url": "https://www.wmaccess.com/downloads/sample-invoice.pdf"
    }
}

"variables": {
    "document": {
        "file_url": "data:application/pdf;base64,JVBERi0xLjUKJeLjz9MKNCAwIG9ia..."
    }
}

"variables": {
    "document": {
        "file_url": "vault://3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
}

Os formatos aceitos (PDF, imagens, áudio, vídeo, documentos Office, CSV e texto simples) estão listados em Formatos de arquivo suportados.

Com os SDKs

Os SDKs montam o arquivo para você: tela.createFile (TypeScript e JavaScript) e client.create_file (Python) aceitam uma URL e constroem o objeto file_url. createFile também aceita um Buffer, um Blob ou um stream de leitura, e create_file aceita um arquivo aberto, então você envia arquivos locais sem codificá-los por conta própria.

import fs from 'node:fs'
import type { TelaFile } from '@meistrari/tela-sdk-js'

const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        // A URL...
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
        // ...or a local file
        // document: tela.createFile(fs.createReadStream('./sample-invoice.pdf')),
    },
})

import fs from 'node:fs'

const completion = await tela.completions.create({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        // A URL...
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
        // ...or a local file
        // document: tela.createFile(fs.createReadStream('./sample-invoice.pdf')),
    },
})

# A URL...
completion = client.completions.create(
    canvas_id=TELA_CANVAS_ID,
    variables={
        "document": client.create_file("https://www.wmaccess.com/downloads/sample-invoice.pdf"),
    },
)

# ...or a local file
with open("./sample-invoice.pdf", "rb") as file:
    completion = client.completions.create(
        canvas_id=TELA_CANVAS_ID,
        variables={
            "document": client.create_file(file),
        },
    )

Vários arquivos em uma variável

Uma variável pode receber um array de objetos de arquivo. Você pode misturar arquivos públicos e enviados no mesmo array.

variables: {
    documents: [
        { file_url: 'https://example.com/file1.pdf' },
        { file_url: 'https://example.com/file2.pdf' },
        { file_url: 'vault://550e8400-e29b-41d4-a716-446655440000' },
    ],
},

variables={
    "documents": [
        {"file_url": "https://example.com/file1.pdf"},
        {"file_url": "https://example.com/file2.pdf"},
        {"file_url": "vault://550e8400-e29b-41d4-a716-446655440000"},
    ],
}

"variables": {
    "documents": [
        { "file_url": "https://example.com/file1.pdf" },
        { "file_url": "https://example.com/file2.pdf" },
        { "file_url": "vault://550e8400-e29b-41d4-a716-446655440000" }
    ]
}

Enviando um arquivo antes

Quando um arquivo não é público e é grande demais para ir inline, envie-o para o Tela e referencie-o pelo ID. O envio tem duas etapas com POST /v3/files, que exige o header x-compatibility-date (veja Data de compatibilidade).

Solicitar uma URL de upload

Envie o nome do arquivo. A resposta traz o id do arquivo e uma uploadUrl temporária.

cURL

curl -X POST https://api.tela.com/v3/files \
    -H "Authorization: Bearer $TELA_API_KEY" \
    -H 'x-compatibility-date: 2025-07-23' \
    -H 'Content-Type: application/json' \
    -d '{ "fileName": "sample-invoice.pdf" }'

Resposta

{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "uploadUrl": "https://file-upload-temporary.example.com/upload?token=xyz"
}

Enviar o conteúdo

Faça um PUT dos bytes para a uploadUrl, informando o Content-Type do arquivo. A URL expira em pouco tempo, então envie logo em seguida.

cURL

curl -X PUT "UPLOAD_URL_FROM_PREVIOUS_STEP" \
    -H 'Content-Type: application/pdf' \
    --data-binary @sample-invoice.pdf

Referenciar na completion

Use vault://<id> como file_url da variável. O arquivo só pode ser lido dentro do seu Workspace.

Corpo HTTP

"variables": {
    "document": { "file_url": "vault://3fa85f64-5717-4562-b3fc-2c963f66afa6" }
}

GET /v3/files/{id} retorna os metadados de um arquivo enviado (fileName, size, mimeType, createdAt e uma url). O passo a passo completo, com exemplos em TypeScript e Python, está em Upload a File (v3).

O endpoint mais antigo POST /v2/file também retorna uma upload_url para o PUT do arquivo, junto com uma download_url que você pode passar como uma file_url comum. Veja Upload a File. Integrações novas devem usar /v3/files.

Onde os arquivos aparecem depois

Toda execução registra as suas entradas. No resultado de uma execução assíncrona e no histórico de execuções, input_content.variables guarda os valores que você enviou e input_content.files lista cada arquivo com o seu name (o nome da variável), a url e used_at: "variables".

Primeiros passos

Construir

Testar

Operar

Integrar

Variáveis e arquivos

Texto

Arquivos

Com os SDKs

Vários arquivos em uma variável

Enviando um arquivo antes

Onde os arquivos aparecem depois

​Texto

​Arquivos

​Com os SDKs

​Vários arquivos em uma variável

​Enviando um arquivo antes

​Onde os arquivos aparecem depois

Texto

Arquivos

Com os SDKs

Vários arquivos em uma variável

Enviando um arquivo antes

Onde os arquivos aparecem depois