Versões e ambientes

Um Canvas tem muitas versões, mas só as publicadas em um ambiente 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.

cURL

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

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.

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

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()

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.

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

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()

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 retorna a versão que Production serve e Get environment version 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.

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.

Corpo HTTP

{
    "canvas_id": "95cec438-6080-44fe-8275-28b16bd40178",
    "variables": { "document": "Document content" },
    "override": {
        "type": "chat",
        "temperature": 0
    }
}

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.

Primeiros passos

Construir

Testar

Operar

Integrar

Versões e ambientes

Production por padrão

Apontando para outro ambiente

Fixando uma versão

Sabendo qual versão executou

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

​Production por padrão

​Apontando para outro ambiente

​Fixando uma versão

​Sabendo qual versão executou

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

Production por padrão

Apontando para outro ambiente

Fixando uma versão

Sabendo qual versão executou

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