Pular para o conteúdo principal
A Completion API é a forma de os seus próprios sistemas executarem um Canvas. Uma requisição para 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.
Menu do Canvas com 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.
Modal Conectar via API

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 um canvas_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 objeto chat.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.
A resposta é diferente quando você usa streaming (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.
As tags enviadas na requisição são combinadas com as tags configuradas no Canvas e servem para filtrar execuções anteriores. Veja Tags para a sintaxe, incluindo tags dinâmicas como tipo-$output.categoria.

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 o application_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 como variables e leia o resultado do mesmo jeito. Para acompanhar cada etapa de uma execução, use a API de Workflow Run.