Skip to main content
Pré-requisitos:

​
Obtenha os dados do seu canvas

Precisamos de duas coisas para começar a usar nosso canvas:
  1. Chave de API
  2. Canvas ID
Podemos achar os dois no mesmo local.
1

Abrir opções de Deploy

Primeiro clique no botão de implantação no canto superior direito da interface do aplicativo. Isso abrirá as opções de implantação.Deploy
2

Abrir modal de conexão com a API

Lá você encontrará como implantar aplicativos e como se conectar à API, clique em “Or connect directly via API” na parte inferior do modal.Deploy
3

Pegue os dados

Aqui você encontrará todas as informações necessárias para começar a integrar! Escolha sua linguagem preferida para começar.Deploy

​
Construindo o Corpo da Chamada do Canvas

Para alcançar o comportamento desejado para o seu negócio e integração, sua chamada de canvas pode incluir variáveis, mensagens históricas, streaming e respostas de webhook para integrações assíncronas.
Confira a Referência da API para mais detalhes sobre nosso SDK e especificações da API.

​
Usando Variáveis

Variáveis são um conceito chave na construção de prompts com o Tela. Elas são usadas para armazenar e reutilizar dados ao longo dos seus prompts e podem ser uma entrada manual ou um arquivo.
Para informações sobre formato de arquivos suportados, visite Formato suportados.
Quando definimos variáveis em nosso prompt, o modal de conexão gerará os trechos de código para nós já preenchidos com as chaves das variáveis. Deploy Preencha as chaves com os valores que você deseja, pode ser um texto, uma URL de arquivo ou uma string base64 de arquivo. 
variables: {
    document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'), // It is possible to pass a URL, Buffer, Blob, etc.
},
Confira os detalhes de uso de arquivos com nosso SDK

​
Usando Mensagens

A API do Tela permite que você inclua mensagens em suas requisições, estendendo o corpo da requisição com a chave messages. Esse recurso permite que você forneça contexto ou informações adicionais ao modelo, melhorando a interação e a qualidade da saída. 
const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf')
    },
    messages: [
        {
            role: 'user',
            content: {
                type: 'text',
                text: 'Hello, how can I assist you today?'
            }
        },
        {
            role: 'assistant',
            content: {
                type: 'image_url',
                image_url: {
                    url: 'https://example.com/image.png',
                    detail: 'high'
                }
            }
        }
    ]
})
A sequência de mensagens no array é crucial, pois representa o fluxo cronológico da conversa. Cada ciclo começa com a mensagem de um usuário e é seguido pela resposta do assistente, mantendo o contexto e a coerência do diálogo.
Confira a Referência da API para mais detalhes sobre o esquema do campo mensagens.

​
Streaming

Para habilitar o streaming na chamada do canvas, basta incluir a chave stream definida como true no corpo da requisição. 
const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf')
    },
    stream: true
})
Veja a Referência da API de Streaming para mais detalhes sobre o consumo do stream.

​
Async

Para alcançar um comportamento assíncrono, você tem duas opções:
  • Usando a flag async
  • Usando um webhook

​
Usando a Flag Async

Para usar a flag async, basta incluí-la no corpo da requisição e defini-la como true. Isso fará com que a execução seja assíncrona, permitindo que você continue com outras tarefas enquanto aguarda a conclusão. Um id sera retornado para que você possa monitorar o status da chamada. 
curl -XPOST https://api.tela.com/v2/chat/completions \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer API-KEY' \
    -d '{
        ...,
        "async": true
    }'
Veja a Referência da API de Obtenção de Completion Assíncrona para mais detalhes de como consumir a completion com o id recebido

​
Usando Webhook

Você pode passar uma URL de webhook para nossa API, estendendo o corpo com uma chave webhook_url, isso tornará a chamada assíncrona, e você receberá a resposta quando a completion for finalizada com uma requisição POST na URL fornecida. 
const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf')
    },
    webhook_url: "https://example.com/webhook"
})
Quando a chave webhook_url é usada, a chamada se torna assíncrona automaticamente, eliminando a necessidade de incluir a flag async.

​
Estrutura do Payload do Webhook

Quando sua completion é finalizada, o Tela enviará uma requisição POST para sua URL de webhook com a seguinte estrutura: Headers:
  • x-completion-run-id: O identificador único da execução da completion
  • Content-Type: application/json
Body: O payload do webhook contém o resultado bruto da completion: 
{
    "usage": {
        "total_tokens": <number>,
        "prompt_tokens": <number>,
        "completion_tokens": <number>
    },
    "object": "chat.completion",
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": <... conteúdo da sua completion>
            }
        }
    ],
    "created": <timestamp>
}
Você pode usar o header x-completion-run-id para correlacionar a resposta do webhook com sua requisição original e acompanhar o status da completion em sua aplicação.