> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral da Completion API

> Execute um Canvas ou Workflow publicado a partir do seu código com POST /v2/chat/completions

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](https://docs.tela.com/pt/completion-api/variables-and-files.md)**
>
> Preencha as variáveis do Canvas com texto, URLs de arquivo, conteúdo em base64 ou arquivos enviados

> **[Mensagens](https://docs.tela.com/pt/completion-api/messages.md)**
>
> Envie um histórico de conversa junto com as variáveis

> **[Versões e ambientes](https://docs.tela.com/pt/completion-api/versions-and-environments.md)**
>
> Controle qual versão do Canvas é executada

> **[Streaming](https://docs.tela.com/pt/completion-api/streaming.md)**
>
> Receba a resposta enquanto ela é gerada

> **[Assíncrono e webhooks](https://docs.tela.com/pt/completion-api/async-and-webhooks.md)**
>
> Execute em segundo plano, consulte o resultado ou receba um callback, e liste execuções anteriores

> **[Erros e retentativas](https://docs.tela.com/pt/completion-api/errors-and-retries.md)**
>
> Códigos de status, o corpo do erro e o que é seguro repetir

## Pré-requisitos

* Um [Canvas publicado](https://docs.tela.com/pt/craft/publishing.md). 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](https://docs.tela.com/api-reference/introduction.md#authentication).
* 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](https://mintcdn.com/meistrari/jZ7VrspVjrdqJJQA/images/pt/guides/integrating-api/deploy-focus.png?fit=max\&auto=format\&n=jZ7VrspVjrdqJJQA\&q=85\&s=9554ffe376fcc69d17be5352810e7569)

**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](https://mintcdn.com/meistrari/jZ7VrspVjrdqJJQA/images/pt/guides/integrating-api/api-connect-focus.png?fit=max\&auto=format\&n=jZ7VrspVjrdqJJQA\&q=85\&s=f5784a562e91418fb043bbb1d99cb920)

## 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](https://docs.tela.com/api-reference/completion/create.md), 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.

```typescript TypeScript Tela SDK theme={null}
import { createTelaClient } from '@meistrari/tela-sdk-js'

const tela = createTelaClient({
    apiKey: process.env.TELA_API_KEY,
})

const completion = await tela.completions.create<{ document: string }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: 'Document content',
    },
})

console.log(completion.choices[0].message.content)
```

```javascript JavaScript Tela SDK theme={null}
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: 'Document content',
    },
})

console.log(completion.choices[0].message.content)
```

```python Python Tela SDK theme={null}
import os
from tela import create_tela_client

TELA_CANVAS_ID = os.getenv("TELA_CANVAS_ID")
TELA_API_KEY = os.getenv("TELA_API_KEY")

client = create_tela_client(
    api_key=TELA_API_KEY,
)

completion = client.completions.create(
    canvas_id=TELA_CANVAS_ID,
    variables={
        "document": "Document content",
    },
)

print(completion.choices[0].message.content)
```

```sh cURL theme={null}
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": "Document content"
        }
    }'
```

## 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](https://docs.tela.com/pt/craft/output-format.md) quando o Canvas tem um, ou o texto da resposta caso contrário.

```json Com Formato de Saída theme={null}
{
    "id": "crsv-i52z8vnqekc",
    "object": "chat.completion",
    "created": 1728399621,
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": {
                    "rationale": "The content of the PDF is not provided, so a summary cannot be generated.",
                    "message": "No summary can be generated."
                }
            }
        }
    ]
}
```

```json Texto simples theme={null}
{
    "id": "crsv-i52z8vnqekc",
    "object": "chat.completion",
    "created": 1728399621,
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": {
                    "text": "The content of the PDF is not provided, so a summary cannot be generated."
                }
            }
        }
    ]
}
```

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](https://docs.tela.com/pt/completion-api/streaming.md) e [Assíncrono e webhooks](https://docs.tela.com/pt/completion-api/async-and-webhooks.md).

## Campos da requisição

| Campo | Tipo | O que faz |
| - | - | - |
| `canvas_id` | string | Executa o Canvas. Por padrão, a versão publicada em **Production**. |
| `version_id` | string | Executa uma versão exata em vez de um Canvas. |
| `application_id` | string | Cria uma tarefa em um App da Workstation em vez de uma completion. |
| `environment_name` | string | Com `canvas_id`, executa a versão publicada nesse ambiente. |
| `variables` | object | Valores para as variáveis do Canvas: texto ou arquivos. |
| `messages` | array | Histórico de conversa enviado junto com as variáveis. |
| `stream` | boolean | Transmite a resposta enquanto ela é gerada. |
| `async` | boolean | Retorna de imediato e permite consultar o resultado depois. |
| `webhook_url` | string | Torna a execução assíncrona e envia o resultado por POST para essa URL. |
| `tags` | array de strings | Rótulos guardados com a execução, combinados com as tags do Canvas. |
| `override` | object | Substitui configurações de modelo do Canvas só nesta 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.

> [!TIP]
>
> As tags enviadas na requisição são combinadas com as tags configuradas no Canvas e servem para filtrar execuções anteriores. Veja [Tags](https://docs.tela.com/pt/tags.md#enviando-tags-via-api) 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](https://docs.tela.com/pt/creating-tasks.md).

## Executando um Workflow

Um [Workflow publicado](https://docs.tela.com/pt/creating-your-first-workflow.md#executando-testando-e-publicando) é 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](https://docs.tela.com/api-reference/workflow-run/get-workflow-runs.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.