# Chaves de provedor

> Adicione as chaves de provedor do Nodaro self-hosted em /setup ou no .env, veja qual chave habilita quais nós e passe o tráfego pelo seu próprio proxy.

Source: https://nodaro.ai/pt-BR/docs/self-hosting/provider-keys

As **chaves de provedor** são as chaves de API que permitem que um Nodaro self-hosted chame modelos de IA. Você pode colá-las no app ou defini-las no ambiente, e as duas formas valem ao mesmo tempo. Em vez de chaves, ou junto com elas, você também pode conectar a instalação a uma conta do Nodaro Cloud: veja [Conectar ao Nodaro Cloud](https://nodaro.ai/docs/self-hosting/cloud-connect).

## Duas formas de adicionar uma chave
| Forma | Onde a chave fica | Quando passa a valer | Quem pode alterá-la |
| --- | --- | --- | --- |
| **Colar no app**, em `/setup`, na seção **Integridade da instalação**, ou em **Integrações › Provedores de modelos** | No seu banco de dados, criptografada com a chave da instância. Nenhuma rota a retorna. | Na hora. A API a usa imediatamente, e os workers a leem em cerca de 30 segundos. Sem reinicialização. | Community: qualquer usuário logado. Business: os administradores. |
| **Definir no ambiente**, no `.env` ou nas variáveis da sua plataforma | No seu ambiente | Na inicialização seguinte | Quem gerencia o servidor |

Clicar em **Executar** logo depois de colar uma chave funciona: um nó que não encontra um provedor lê as chaves de novo, uma vez, antes de falhar.

Colar uma chave sempre exige uma sessão logada no app. Um token de API ou um token de app nunca pode alterar uma chave. Os cartões de integridade de `/setup` não exigem login, mas salvar uma chave ali exige: conclua primeiro a etapa 1, **Crie seu login do servidor**.

## Qual chave prevalece
**O ambiente prevalece.** Uma chave definida no ambiente fica somente leitura na tela: o bloco dela mostra `set (env)` e indica a variável a remover. Uma chave colada só é usada quando o ambiente não tem nenhuma chave para aquele provedor.

## Gerenciar uma chave no bloco dela
Todo bloco de provedor pode ser gerenciado em tempo de execução, inclusive as chaves que vêm do `.env`. As alterações passam a valer sem reinicialização.

- **Uma chave colada** mostra `set (app)`, ou `key set (app)` no bloco **nodaro.ai**. Clique em **Alterar chave** ou em **Remover** a qualquer momento.
- **Uma chave do `.env`** não pode ser editada ali mesmo. **Substituir chave do .env** salva no app uma chave que sobrepõe a do ambiente, sem editar o arquivo. Ou remova a chave do `.env` e reinicie.
- **Desativar** interrompe um provedor até você ativá-lo de novo, quer a chave dele venha do `.env`, quer tenha sido colada. Use essa opção para mover a geração para outro provedor, por exemplo para a sua conexão com o Nodaro Cloud.
- **`missing`** (**ausente**) significa que o provedor não tem chave. **`disabled`** (**desativado**) significa que você o desligou.

Cada bloco diz o que a chave dele habilita e onde conseguir uma.

## Todas as chaves de provedor
| Variável | O que habilita |
| --- | --- |
| `NODARO_API_KEY` | O Nodaro Cloud como provedor: um token de API pessoal do app.nodaro.ai › **Configurações › Tokens de API**, cobrado dessa conta. Veja [Conectar ao Nodaro Cloud](https://nodaro.ai/docs/self-hosting/cloud-connect#or-use-an-api-key-like-any-other-provider). |
| `KIE_API_KEY` | A maior cobertura de modelos: modelos de imagem, vídeo, áudio e texto, incluindo os nós de música do Suno. |
| `REPLICATE_API_TOKEN` | Um provedor alternativo, com catálogo próprio, incluindo os modelos Flux 2. |
| `ANTHROPIC_API_KEY` | Modelos Claude para os nós de texto, chamados diretamente. |
| `GEMINI_API_KEY` | Modelos Gemini, chamados diretamente. Uma chave do Google AI Studio. Veja [Modelos Gemini](#gemini-models). |
| `ELEVENLABS_API_KEY` | Fala, vozes, dublagem, modificador de voz e alinhamento forçado. |
| `FAL_KEY` | Opcional. Modelos como o [Sync Lipsync v3](https://nodaro.ai/docs/models/video/sync-lipsync-v3). Sem ela, esses modelos ficam indisponíveis, e nada mais muda. |

### Chaves usadas por nós específicos
Deixe estas chaves vazias, a menos que você use o nó que elas indicam. Em uma instalação conectada, esses nós são executados pelo Nodaro Cloud quando a chave deles está vazia.

| Variável | Nós |
| --- | --- |
| `HEYGEN_API_KEY` | [**Avatar de IA** (AI Avatar)](https://nodaro.ai/docs/nodes/video/ai-avatar) e [**Avatar cinematográfico** (Cinematic Avatar)](https://nodaro.ai/docs/nodes/video/cinematic-avatar) |
| `BEEBLE_API_KEY` | [**Reiluminar e trocar** (Relight & Switch)](https://nodaro.ai/docs/nodes/video/relight-and-switch) |
| `APIFY_API_TOKEN` | [**Extrair da web** (Web Scrape)](https://nodaro.ai/docs/nodes/automate/web-scrape) |

`GEMINI_API_KEY` não é o mesmo que `GOOGLE_CLIENT_ID` e `GOOGLE_CLIENT_SECRET`. Essas duas variáveis pertencem a um app OAuth do Google, por exemplo para publicar no YouTube. Veja [Apps das redes sociais](https://nodaro.ai/docs/self-hosting/configuration#social-network-apps).

## As chaves e a conexão com o Nodaro Cloud
- **Uma conexão cobre todos os blocos.** Em uma instalação conectada, os modelos de imagem, vídeo, fala e texto, os avatares, o Reiluminar e trocar e a extração de dados da web são executados pela sua conta do Nodaro Cloud. Cole uma chave só para chamar aquele provedor diretamente.
- **Você escolhe quem tem prioridade.** Quando você se conecta, uma caixa de diálogo pergunta se o Nodaro Cloud executa tudo primeiro ou se as suas próprias chaves vêm primeiro. Veja [Escolher como a conexão é usada](https://nodaro.ai/docs/self-hosting/cloud-connect#choose-how-the-connection-is-used).
- **A conexão OAuth prevalece sobre a `NODARO_API_KEY`.** Quando uma instalação tem as duas, ela usa a conexão e ignora a chave.

## Modelos Gemini
Os modelos Gemini podem rodar de duas formas. Sem a `GEMINI_API_KEY`, eles rodam com a `KIE_API_KEY`. Com ela:

- O **Gemini 3.1 Pro** roda primeiro diretamente no Google, com a `KIE_API_KEY` como alternativa.
- **Os modelos Gemini Flash** continuam na `KIE_API_KEY` e só usam a `GEMINI_API_KEY` quando essa rota falha.

Duas coisas para saber antes de defini-la:

- **Custo.** O Google cobra a rota direta pelos próprios preços por token, que podem ser mais altos que os do mesmo modelo na `KIE_API_KEY`. Confira os preços atuais do Google antes de mover um modelo de alto volume.
- **Mídia.** A API do Google não consegue buscar URLs arbitrárias. O Nodaro baixa cada referência de imagem, vídeo ou áudio e a envia como dados inline, quando ela é pequena, ou pela Gemini Files API, quando ela é grande. A Files API guarda os arquivos por 48 horas.

## Passar o tráfego dos provedores pelo seu próprio proxy
Dois provedores permitem mudar o host, e não só a chave:

| Variável | Padrão | O que ela redireciona |
| --- | --- | --- |
| `KIE_API_BASE_URL` | O host de API do próprio provedor | Todas as chamadas feitas com a `KIE_API_KEY`: a geração de mídia **e** o tráfego de texto do Claude e do Gemini que roda com ela |
| `ELEVENLABS_BASE_URL` | `https://api.elevenlabs.io` | Todas as chamadas à ElevenLabs: texto para fala, fala para texto, vozes, clonagem, dublagem e alinhamento forçado |

Deixe as duas sem definir, e nada muda. Defina uma, e o Nodaro passa a se comunicar com o seu host. Os motivos comuns são a custódia das chaves, em que a chave real fica só no proxy, um log de auditoria de cada geração que sai da instalação e o roteamento regional.

O seu proxy precisa ser transparente: os mesmos caminhos e os mesmos corpos de requisição e de resposta, porque o Nodaro só troca a origem. As barras finais são removidas, então `https://proxy.example.com/models/` e `https://proxy.example.com/models` se comportam da mesma forma.

**KIE_API_BASE_URL também redireciona o tráfego dos modelos de texto:** 
O tráfego do Claude e do Gemini por trás do aprimoramento de prompts, da geração de roteiros e dos outros recursos de texto passa pelo mesmo host. O seu proxy precisa encaminhar estes caminhos, e não só a API de mídia:

- `/api/v1/...`, para as tarefas, a consulta periódica e a verificação de saldo
- `/claude/v1/messages`
- `/<family>/v1/chat/completions`
- `/<family>/v1/responses`
- `/client/v1/userRecord/...`, para as consultas de créditos

Um proxy que só encaminha os caminhos de mídia deixa todos os recursos de texto falhando, enquanto as imagens e os vídeos continuam funcionando.

`ANTHROPIC_API_KEY` e `GEMINI_API_KEY` não são afetadas pelo proxy. Com elas, esses modelos chamam a Anthropic e o Google diretamente.

## Verificar se uma chave funciona
- **No editor.** Abra o workflow Welcome Demo e clique em **Executar** no nó **Imagem da cena** (Scene Image) dele.
- **Pela linha de comando.** Rode o teste com `--keyed`. Ele gasta uma geração real no modelo mais barato para a sua `KIE_API_KEY` ou o seu `REPLICATE_API_TOKEN` e verifica se a mídia chega ao seu próprio armazenamento:

```bash
node tools/community-smoke.mjs http://localhost:3000 --keyed
```

Um nó que falha com `Missing API key` chama um provedor que não tem chave. Adicione a chave desse provedor em `/setup` ou no `.env`.

## A chave de criptografia
As chaves coladas precisam da chave de criptografia da instância, `NODARO_ENCRYPTION_KEY`. A stack do Compose incluída a gera na primeira inicialização. Sem ela, os blocos mostram `missing` (**ausente**), e `/setup` mostra um cartão **Criptografia** vermelho com a correção. As chaves definidas no ambiente continuam funcionando. Veja [Instalação](https://nodaro.ai/docs/self-hosting/install#2-generate-the-internal-secrets).

## Frequently asked questions

### Onde adiciono as chaves de provedor em um Nodaro self-hosted?

Cole-as em /setup, na seção Integridade da instalação, ou no app, em Integrações › Provedores de modelos. Ou defina-as no .env e rode docker compose up -d. As chaves coladas passam a valer na hora, sem reinicialização.

### Qual prevalece: uma chave no .env ou uma chave colada na tela?

A chave do ambiente. O bloco dela mostra set (env) e não pode ser editado ali mesmo. Remova a chave do .env e reinicie, ou use Substituir chave do .env no bloco para sobrepô-la pela tela.

### Quem pode alterar as chaves de provedor?

Na Community Edition, qualquer usuário logado, porque a edição foi feita para um único operador. Na Business edition, só os administradores. Tokens de API e tokens de app nunca podem alterá-las.

### Onde as chaves coladas ficam armazenadas?

No seu próprio banco de dados, criptografadas com AES-256-GCM usando a chave de criptografia da instância. Nenhuma rota as retorna. Sem uma chave de criptografia, os blocos mostram missing (ausente), e /setup mostra um cartão Criptografia vermelho.

### Por que imagem e vídeo funcionam, mas todos os recursos de texto falham?

Se você definiu KIE_API_BASE_URL com um proxy, o proxy também precisa encaminhar os caminhos dos modelos de texto, e não só a API de mídia. Um proxy que só encaminha os caminhos de mídia quebra todos os recursos que usam um modelo de texto.