POST /v2/chat/completions envia as entradas de uma execução (variáveis, arquivos, histórico de conversa) e recebe o que o Canvas produziu, na mesma resposta ou depois, por polling ou por um callback.
O mesmo endpoint também executa um Workflow publicado e cria uma tarefa em um App da Workstation quando você passa um application_id em vez de um canvas_id. Esta seção cobre todas as formas de chamá-lo:
Variáveis e arquivos
Preencha as variáveis do Canvas com texto, URLs de arquivo, conteúdo em base64 ou arquivos enviados
Mensagens
Envie um histórico de conversa junto com as variáveis
Versões e ambientes
Controle qual versão do Canvas é executada
Streaming
Receba a resposta enquanto ela é gerada
Assíncrono e webhooks
Execute em segundo plano, consulte o resultado ou receba um callback, e liste execuções anteriores
Erros e retentativas
Códigos de status, o corpo do erro e o que é seguro repetir
Pré-requisitos
- Um Canvas publicado. Só versões publicadas em um ambiente podem ser executadas pela API, e um Rascunho precisa ser movido para um Projeto antes.
- Uma chave de API, criada nas configurações do Workspace, em API Keys. Mantenha-a no seu servidor. Veja Autenticação.
- O ID do Canvas, obtido em Conectar via API.
1
Abrir Conectar via API
Clique no botão 
… ao lado do título do seu Canvas, no canto superior esquerdo da página, e selecione Conectar via API.
2
Copiar o ID do Canvas e um snippet
O diálogo mostra o ID do seu Canvas e um snippet pronto para uso na linguagem que você escolher. O snippet já lista as variáveis do Canvas.

SDK ou HTTP
Você pode chamar a API com os SDKs do Tela (@meistrari/tela-sdk-js para TypeScript e JavaScript, tela para Python) ou com qualquer cliente HTTP. Os SDKs mapeiam os campos da requisição para camelCase (canvasId, applicationId) e acrescentam utilitários como createFile. Por HTTP, você envia os campos exatamente como aparecem na referência da API, em snake_case.
Toda requisição HTTP vai para https://api.tela.com, com Content-Type: application/json e Authorization: Bearer SUA_CHAVE_DE_API.
Requisição mínima
Só com umcanvas_id e as variáveis, a chamada executa a versão publicada em Production e espera pelo resultado.
A resposta
Uma chamada síncrona responde com um objetochat.completion. O resultado está em choices[0].message.content: um objeto com os campos do seu Formato de Saída quando o Canvas tem um, ou o texto da resposta caso contrário.
stream: true) ou executa em segundo plano (async: true ou webhook_url). Esses formatos estão descritos em Streaming e Assíncrono e webhooks.
Campos da requisição
Exatamente um entre
canvas_id, version_id e application_id identifica o que executar. stream e async só estão disponíveis com canvas_id e version_id: tarefas sempre rodam de forma assíncrona.
Completions ou tarefas?
Uma completion é uma execução sem estado: você envia as entradas, recebe a saída, e a execução fica registrada no Usage do Canvas. Use quando o seu sistema é quem consome o resultado. Uma tarefa é uma execução criada dentro de um App da Workstation, onde o seu time revisa, edita e aprova a saída antes de ela ser usada. Use quando uma pessoa precisa conferir cada resultado, ou quando você quer que os resultados aprovados alimentem Casos de Teste. Para criar uma, passe oapplication_id do App em vez do canvas_id; o resto da requisição é igual. Tarefas são sempre assíncronas e são lidas de volta pelos endpoints /task. Veja Criando tarefas via API.
Executando um Workflow
Um Workflow publicado é executado da mesma forma que um Canvas: conecte-o via API, envie as suas Entradas comovariables e leia o resultado do mesmo jeito. Para acompanhar cada etapa de uma execução, use a API de Workflow Run.