Automatize o Transept com a API

Crie uma chave de API pessoal em Configurações → Desenvolvedor. Ela está disponível em todos os planos, inclusive no Gratuito — não há barreiras adicionais; o que limita o uso é o seu saldo de palavras. Dê um nome à chave, defina uma expiração (opcional) e copie o segredo quando ele for exibido: ele aparece apenas uma vez e não poderá ser recuperado depois. Revogue uma chave a qualquer momento na mesma página.

As requisições são autenticadas com a chave em um cabeçalho Authorization: Bearer tsk_live_… — apenas no cabeçalho, nunca em uma URL.

Com apenas seis chamadas curtas, você vai de uma chave de API ao resultado traduzido. Apenas a execução da tradução em si consome palavras; as estimativas são gratuitas e chamadas repetidas com a mesma Idempotency-Key retornam o resultado original em vez de cobrar duas vezes.

As mesmas chamadas, com explicações detalhadas, estão em transept.ai/developers. O guia da API de localização explica o restante: catálogos de strings, templates de e-mail, glossários, equipes e etapas de revisão.

export KEY="tsk_live_…"                          # minted under Settings → Developer
BASE="https://app.transept.ai/api/public/v1"

# 1. Check the key: your account, its permissions, your word balance
curl -s $BASE/me -H "Authorization: Bearer $KEY"

# 2. Create a document; Transept creates one language version per target
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Welcome email", "content": "# Welcome…", "content_type": "markdown",
       "source_language": "en", "target_languages": ["de", "fr", "uk"]}'

# 3. Estimate: the word cost, free, with no side effects
curl -s -X POST $BASE/group-runs/estimate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'

# 4. Run: the same body starts it
curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-1" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'

# 5. Wait: poll for per-language progress (or get pushed an event; see below)
curl -s $BASE/group-runs/<group-run-id> -H "Authorization: Bearer $KEY"

# 6. Read each language back in the format you need (the table below lists them)
curl -s "$BASE/documents/<version-id>/content?format=markdown" \
  -H "Authorization: Bearer $KEY"

Crie um documento a partir de texto simples, HTML ou markdown, ou faça o upload de um arquivo — os mesmos formatos aceitos pelo aplicativo. Você também pode importar uma tabela de strings (.tstrings.json): um formato estruturado para textos de interface ou strings de jogos, no qual cada string é uma unidade com uma chave estável e seu próprio contexto — uma nota sobre o que ela é, onde aparece, o limite de caracteres e o significado de seus placeholders. Tudo isso chega ao modelo; placeholders como {name} são protegidos contra remoção ou renomeação, e os plurais são expandidos conforme o idioma (uma forma em inglês torna-se duas em alemão, quatro em ucraniano). Quaisquer traduções que o arquivo já contenha são importadas como estão, sem custo, e alimentam a memória de tradução imediatamente.

Uma execução em grupo traduz para vários idiomas de uma só vez. Você informa o documento, o workflow ou template a ser executado e os idiomas de destino; o Transept cria as versões de idioma que faltarem e executa o workflow em cada uma delas. Um único ID rastreia todo o processo — consulte-o para acompanhar o progresso de cada idioma e verificar se há algo aguardando revisão.

Para execuções recorrentes, envie novamente o arquivo atual de uma tabela de strings e o Transept identifica o que mudou: as strings inalteradas mantêm suas traduções (e qualquer revisão já feita), e a execução processa apenas as unidades novas ou que foram realmente modificadas — a versão via API de Executar apenas o que mudou. Todo esse fluxo baseado em chaves, desde a primeira importação até as execuções incrementais, está em Localizar um catálogo de strings via API.

Em vez de fazer polling, registre uma URL e o Transept enviará um evento quando uma execução terminar ou falhar, quando uma revisão estiver pronta para análise, quando o processamento de um upload for concluído e quando uma exportação estiver pronta. Cada entrega contém um cabeçalho HMAC-SHA256 X-Transept-Signature: t=…,v1=… para que o seu servidor verifique se a mensagem realmente veio de nós, e um endpoint com falha passa por novas tentativas com backoff antes de ser desativado.

# register once; every matching event is POSTed to your URL, signed
curl -s -X POST $BASE/webhooks \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/transept-events",
       "events": ["group_run.completed", "run.gate_ready", "run.failed"]}'
# → the endpoint, including its ONE-TIME secret; verify X-Transept-Signature with it

Um workflow também pode ser executado automaticamente a partir de uma automação de banco de dados do Notion: aponte o webhook da automação para a URL de gatilho e o Transept executará o workflow na página que foi alterada. O detalhe é que um webhook do Notion nunca envia o conteúdo da página — ele apenas informa qual página disparou o gatilho. O Transept lê essa página por meio da sua conexão com o Notion, portanto, duas condições precisam ser atendidas; caso contrário, cada disparo será rejeitado com um erro de acesso e o card do gatilho exibirá o aviso “não foi possível ler a página do Notion”:

• Conecte o Notion no Transept — em Configurações → Integrações. Esse é o link de autorização OAuth único que permite ao Transept ler dados em seu nome.
• Compartilhe o banco de dados de origem com a integração dentro do Notion — abra o banco de dados (ou página), clique no menu •••, escolha Conexões e adicione o Transept. Conectar o Notion nas Configurações não concede acesso a um banco de dados específico por si só; sem essa etapa, a conexão estará ativa, mas a página continuará inacessível.
• Dispare com base na alteração de uma propriedade, não apenas na edição do corpo. As automações do Notion são acionadas por mudanças em propriedades (e adição de páginas), portanto, editar apenas o corpo de uma página pode não disparar nada. O padrão mais confiável é usar uma propriedade de Status monitorada pela automação — altere-a (por exemplo, para “Pronto para traduzir”) e essa mudança será o que acionará o gatilho.

A lista completa de endpoints é publicada como uma especificação OpenAPI que você pode importar para o n8n, Zapier ou um gerador de código: explore a referência interativa ou obtenha o JSON bruto. Prefere um passo a passo? O transept.ai/developers traz o guia de início rápido com exemplos de copiar e colar, e o guia da API de localização detalha todo o fluxo. As execuções iniciadas via API são cobradas por palavra, exatamente como no editor do aplicativo.

Sim — o Transept possui um endpoint MCP ao qual assistentes de IA se conectam: https://app.transept.ai/api/public/v1/mcp. A conexão utiliza o padrão OAuth: adicione a URL ao Claude Code, Claude Desktop, Cursor ou qualquer cliente MCP, e uma janela do navegador solicitará que você aprove o acesso — sem precisar colar chaves (uma chave de API como cabeçalho Bearer ainda funciona para CI e configurações headless). O assistente passa a ter ferramentas para todo o fluxo: importar documentos, executar workflows em vários idiomas, gerenciar glossários e guias de estilo, consultar a memória de tradução e ler os resultados de volta. Duas proteções estão integradas: cada ferramenta respeita as permissões concedidas por você, e qualquer ação que consuma palavras informa primeiro a estimativa de palavras — o assistente deve confirmar explicitamente antes que uma execução comece, para que um agente nunca gere cobranças acidentais. Snippets de configuração prontos para cada cliente estão na página de Integrações no aplicativo; o passo a passo completo, desde a tela de consentimento até a desconexão, está em Conecte seu assistente de IA.