> ## 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.

# Versões e ambientes

> Escolha qual versão do Canvas uma requisição executa: Production, outro ambiente ou uma versão fixa

Um Canvas tem muitas versões, mas só as [publicadas em um ambiente](https://docs.tela.com/pt/craft/publishing.md) ficam acessíveis pela API. Toda requisição executa exatamente uma versão, e qual delas depende de como você identifica o Canvas no corpo.

| Você envia | O que executa |
| - | - |
| `canvas_id` | A versão publicada em **Production** no momento. |
| `canvas_id` + `environment_name` | A versão publicada nesse ambiente no momento. |
| `version_id` | Essa versão exata, independentemente do que está publicado. |

## Production por padrão

Só com um `canvas_id`, a requisição executa a versão publicada em **Production**, o ambiente que todo Canvas tem. Sempre que alguém clica em **Publicar** em Production, a próxima requisição já usa a nova versão.

```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" }
    }'
```

> [!WARNING]
>
> Publicar em um ambiente substitui a versão que aquele ambiente serve, e as chamadas de API que apontam para ele mudam de comportamento imediatamente. Se alguém do time publicar um rascunho do prompt em Production, a sua integração o executa na próxima chamada. As duas seções abaixo mostram como se proteger disso.

## Apontando para outro ambiente

Além de Production, um Canvas pode ter ambientes personalizados, como `staging`, criados no diálogo **Publicar versão** com **+ Novo environment**. Para executar a versão publicada em um deles, acrescente `environment_name` ao lado de `canvas_id`.

```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",
        "environment_name": "staging",
        "variables": { "document": "Document content" }
    }'
```

```typescript TypeScript (fetch) theme={null}
const response = await fetch('https://api.tela.com/v2/chat/completions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.TELA_API_KEY}`,
    },
    body: JSON.stringify({
        canvas_id: process.env.TELA_CANVAS_ID,
        environment_name: 'staging',
        variables: { document: 'Document content' },
    }),
})

const completion = await response.json()
```

```python Python (requests) theme={null}
import os
import requests

response = requests.post(
    "https://api.tela.com/v2/chat/completions",
    headers={"Authorization": f"Bearer {os.getenv('TELA_API_KEY')}"},
    json={
        "canvas_id": os.getenv("TELA_CANVAS_ID"),
        "environment_name": "staging",
        "variables": {"document": "Document content"},
    },
)

completion = response.json()
```

Regras para `environment_name`:

* É o nome que você deu ao ambiente: letras minúsculas, dígitos e hifens simples entre segmentos, com no máximo 64 caracteres. `production` é o nome do ambiente Production.
* Só acompanha `canvas_id`. Não pode ser combinado com `version_id` nem com `application_id`.
* A requisição falha com `404` quando o ambiente não existe ou não tem uma versão publicada.

Uma configuração comum é a mesma integração apontando para `staging` no seu sistema de testes e para Production no sistema em produção, com o nome do ambiente vindo da configuração. Você publica uma versão em `staging`, testa pela API e só então publica em Production.

## Fixando uma versão

Para executar uma versão específica independentemente do que for publicado, envie `version_id` em vez de `canvas_id`. O resto da requisição (variáveis, mensagens, streaming, async, webhooks) é igual.

```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 '{
        "version_id": "76065caa-c519-441a-8fe2-cc43e29664ab",
        "variables": { "document": "Document content" }
    }'
```

```typescript TypeScript (fetch) theme={null}
const response = await fetch('https://api.tela.com/v2/chat/completions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.TELA_API_KEY}`,
    },
    body: JSON.stringify({
        version_id: '76065caa-c519-441a-8fe2-cc43e29664ab',
        variables: { document: 'Document content' },
    }),
})

const completion = await response.json()
```

```python Python (requests) theme={null}
import os
import requests

response = requests.post(
    "https://api.tela.com/v2/chat/completions",
    headers={"Authorization": f"Bearer {os.getenv('TELA_API_KEY')}"},
    json={
        "version_id": "76065caa-c519-441a-8fe2-cc43e29664ab",
        "variables": {"document": "Document content"},
    },
)

completion = response.json()
```

Você encontra o ID de uma versão no **Histórico de Versões** do Canvas (o botão de versão ao lado de **Publicar**), onde cada versão mostra o seu ID. Pela API, [Get promoted version](https://docs.tela.com/api-reference/prompt-version/get-prompt-id-promoted-version.md) retorna a versão que Production serve e [Get environment version](https://docs.tela.com/api-reference/environment/get-environment-version.md) retorna a versão de qualquer ambiente.

Fixar uma versão troca conveniência por controle: uma integração fixa nunca muda de comportamento sem aviso, mas também não recebe correções até você atualizar o `version_id` no seu código. Use um ambiente quando quiser que o time publique sem um deploy do seu lado, e uma versão fixa quando a integração precisar ser revisada antes de qualquer mudança.

## Sabendo qual versão executou

Toda execução registra a versão que usou, então você pode confirmar a sua configuração:

* O resultado de uma execução assíncrona tem um `prompt_version_id`.
* Uma execução listada com `GET /v1/completion-run` tem `promptVersionId` e, quando a requisição usou `environment_name`, o seu `metadata.requestedEnvironmentName` guarda o nome que você enviou.

Veja [Listando execuções anteriores](https://docs.tela.com/pt/completion-api/async-and-webhooks.md#listando-execucoes-anteriores).

## Substituindo configurações de modelo em uma requisição

O objeto opcional `override` substitui algumas configurações da versão só naquela requisição, sem publicar nada. O `type` é obrigatório (`chat` ou `completion`); os outros campos são opcionais:

| Campo | O que substitui |
| - | - |
| `type` | Se é usado um modelo de chat ou de completion. Obrigatório. |
| `model` | O modelo configurado no Canvas. |
| `temperature` | Aleatoriedade da saída, entre 0 e 1. |
| `functions` | Funções que o modelo pode chamar, cada uma com `name`, `description` e `parameters` em JSON Schema. |
| `structured_output` | `enabled` e um `schema` JSON descrevendo a saída. |

```json Corpo HTTP theme={null}
{
    "canvas_id": "95cec438-6080-44fe-8275-28b16bd40178",
    "variables": { "document": "Document content" },
    "override": {
        "type": "chat",
        "temperature": 0
    }
}
```

> [!NOTE]
>
> Overrides não são salvos no Canvas. O `raw_input.override` da execução registra o que foi enviado. Se você precisa de uma mudança em todas as chamadas, publique uma nova versão.


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