Guias

OpenAI por tenant

A chave OpenAI vive no tenant. Modelos padrão: Realtime para voz, gpt-4o para chat, whisper-1 para transcrição, text-embedding-3-small para RAG, gpt-4o-mini para Qualidade.

Atualizado em 04 de maio de 2026

Por que cada tenant tem sua chave

A IA do Interaflow é construída sobre os modelos da OpenAI — Realtime para voz em tempo real, gpt-4o para chat, Whisper para transcrição, embeddings para RAG, gpt-4o-mini para análise leve. Cada tenant traz sua própria chave porque:

Custo é do tenant. Tokens consumidos batem na conta OpenAI do cliente, não na do Interaflow. Sem chave configurada, a IA não funciona.
Limites e quotas são do tenant. Cada conta OpenAI tem suas próprias quotas; o tenant decide upgrade ou downgrade diretamente com a OpenAI.
Segregação de billing. Operações com várias unidades contabilizam separadamente sem precisar de mecanismos extras de rateio.

A política do produto é OpenAI exclusivamente no backend (ver restrições do produto). Outros provedores (Anthropic, Google, AWS Bedrock) não estão suportados como caminho oficial.

Pré-requisitos

Antes de cadastrar:

Conta OpenAI ativa com método de pagamento configurado.
API key gerada em https://platform.openai.com/api-keys. Formato sk-....
(Opcional) Organization ID se a conta tem múltiplas organizações.
(Opcional) Project ID (proj_...) se você quer escopar a chave a um projeto específico — recomendado para isolar billing do Interaflow do resto da operação OpenAI da empresa.

Modelos usados

A configuração expõe três modelos padrão ajustáveis e três fixos pelo produto:

Configuráveis no tenant

Campo	Padrão	Para que serve
Default model	`gpt-realtime-mini`	Modelo da Realtime API usado em Fluxos Conversacionais com voz.
Default chat model	`gpt-4o`	Modelo de chat usado em Fluxos Conversacionais de texto, Recepcionista e Playbook de Vendas.
Transcription model	`whisper-1`	Modelo de transcrição usado para converter gravações em texto (alimenta Qualidade).

Fixados pelo produto

Uso	Modelo
Embeddings (Base de Conhecimento)	`text-embedding-3-small`
Contextual retrieval (RAG, indexação)	`gpt-4o-mini`
Avaliação Qualidade (QA Light)	`gpt-4o-mini` (configurável por Formulário)

Os modelos fixos estão embutidos para garantir consistência de comportamento, custo previsível e compatibilidade com o pipeline interno. Mudanças aqui passam por evolução do produto, não por configuração de tenant.

Cadastrar a chave

Em Configurações → OpenAI, clique em editar.
API key — cole a chave gerada na OpenAI. O backend a armazena criptografada; nunca aparece em log nem no DOM.
Base URL — deixe em branco para usar o endpoint padrão (https://api.openai.com). Use só se sua organização tem proxy ou endpoint customizado (raro).
Organization ID — opcional. Útil quando a conta tem várias organizações.
Project ID — opcional. Recomendado para segregar billing.
Default model / Chat model / Transcription model — ajuste se você precisar de modelo específico (ex.: gpt-4o-mini em vez de gpt-4o para reduzir custo em chat). Confirme que o modelo escolhido está habilitado para sua chave na OpenAI.
Salvar.

A configuração entra em vigor imediatamente. Próximas Conversas em Fluxos Conversacionais e próximas indexações de Conhecimento passam a usar a nova chave.

Implicações de custo

Os principais drivers de custo:

Realtime API (voz) — bem mais caro por minuto que chat de texto. Volume alto de Fluxos com voz exige acompanhamento de custo mensal.
Chat (gpt-4o) — proporcional aos tokens (input + output) por Conversa. Fluxos com retrieval intenso (Conhecimento + Guardrails) consomem mais tokens por interação.
Embeddings — uma vez por documento (na indexação), pequeno. Reindexação ao atualizar documento dobra o custo do documento específico.
Transcrição (Whisper) — proporcional à duração da gravação. Habilitar Qualidade em Campanha de voz dispara transcrição para todas as gravações avaliadas.
gpt-4o-mini (contextual retrieval, Qualidade) — barato; cobre o caso geral.

Rotação da chave

A rotação é manual:

Gere nova chave no painel OpenAI.
Atualize a chave em Configurações → OpenAI no Interaflow.
Confirme funcionamento — teste um Fluxo, uma indexação de Conhecimento, uma transcrição.
Revogue a chave antiga no painel OpenAI.

Cadência recomendada: trimestral, ou imediata em caso de comprometimento.

Limites conhecidos

Sem rotação automática. Rotação é manual.
Sem painel de gasto integrado. Para acompanhar custo, use o dashboard de billing da própria OpenAI.
Sem fallback para outro provedor. A política é OpenAI-only; se a chave estiver inválida, a IA do tenant simplesmente para de funcionar.
Modelos fixos não são configuráveis — embeddings e contextual retrieval seguem decisão de produto.
Sem MFA na configuração da chave; defesa é por SSO/senha do admin que configura.

Erros comuns

Cadastrar chave sem método de pagamento na conta OpenAI. Chave existe mas não funciona; primeira chamada falha com insufficient_quota.
Modelo escolhido não habilitado para a chave. Algumas contas precisam ativar acesso ao gpt-4o ou Realtime manualmente; verifique no painel OpenAI.
Esquecer Project ID quando a conta tem múltiplos projetos — consumo cai no projeto default, dificultando o rateio.
Trocar a chave em pleno horário de pico. Mesmo que a transição seja rápida, a chamada que cair no segundo errado pode falhar. Faça em janela de baixo tráfego.
Chave vazada e não revogada. Vetor de risco; revogue na OpenAI imediatamente e configure nova no Interaflow.