# Conectar ao Nodaro Cloud

> Conecte o Nodaro self-hosted a uma conta do Nodaro Cloud para rodar modelos padrão sem chaves próprias e usar os nós exclusivos, com cobrança em créditos.

Source: https://nodaro.ai/pt-BR/docs/self-hosting/cloud-connect

Uma **conexão com o Nodaro Cloud** torna o Nodaro Cloud mais um provedor de modelos da sua instalação self-hosted, ao lado das suas próprias chaves. Os modelos padrão passam, então, a rodar com o seu saldo do Nodaro Cloud, sem chaves próprias, e os nós exclusivos do Nodaro, que só existem no Nodaro Cloud, funcionam na sua instalação. O uso é cobrado em créditos da conta do Nodaro Cloud conectada.

## O que a conexão acrescenta
- **Um início com um clique.** A conexão faz o seu login no Nodaro Cloud ou cria uma conta. Uma conta nova recebe o bônus único de 1.500 créditos no primeiro login: veja [Créditos grátis](https://nodaro.ai/docs/get-started/free-credits). Os resultados de uma conta gratuita têm marca d’água até a primeira compra de créditos, que também libera todos os modelos.
- **Modelos padrão sem chaves.** A geração de imagens e de vídeos, a fala e os modelos de texto rodam com o seu saldo do Nodaro Cloud.
- **Os nós que precisam da chave de um fornecedor.** [**Avatar de IA** (AI Avatar)](https://nodaro.ai/docs/nodes/video/ai-avatar), [**Avatar cinematográfico** (Cinematic Avatar)](https://nodaro.ai/docs/nodes/video/cinematic-avatar), [**Reiluminar e trocar** (Relight & Switch)](https://nodaro.ai/docs/nodes/video/relight-and-switch) e [**Extrair da web** (Web Scrape)](https://nodaro.ai/docs/nodes/automate/web-scrape) são executados sem chaves próprias.
- **Os nós exclusivos do Nodaro.** Veja [Os nós exclusivos do Nodaro](#the-nodaro-exclusive-nodes).
- **Sem limite diário de gastos** no uso a partir de uma instalação conectada.

Quanto da sua geração passa pela conexão é escolha sua: veja [Escolher como a conexão é usada](#choose-how-the-connection-is-used).

## Conectar a sua instalação
Duas contas estão envolvidas, e só duas: o seu **login do servidor**, que fica no próprio banco de dados da instalação, e a sua **conta do Nodaro Cloud**.

### Iniciar a conexão
Na sua instalação, abra `/setup` e clique em **Conectar o nodaro.ai** na etapa 2. Ou abra **Integrações**, encontre **nodaro.ai** e clique em **Conectar**.

### Aprovar no Nodaro Cloud
O navegador abre a tela de consentimento do Nodaro Cloud. Faça login ou crie uma conta e aprove. A instalação se registra com a própria credencial OAuth e pede exatamente os escopos de que a geração precisa: `assets:write workflows:execute jobs:read credits:read`.

Se esse navegador já estiver logado no Nodaro Cloud, a tela mostra o nome da conta que está prestes a ser conectada. Essa é uma conta do Nodaro Cloud, sem relação com o seu login do servidor. Clique em **Usar outra conta** para conectar outra.

### Voltar para a sua instalação
Você volta para a sua instalação com a conexão ativa. O cartão mostra o seu saldo do Nodaro Cloud em tempo real. Em seguida, uma caixa de diálogo pergunta como a conexão deve ser usada.

- **Uma conexão por instalação.** A conexão pertence à instalação, não a um usuário. Quem clica em **Conectar** vincula a instalação inteira à própria conta do Nodaro Cloud.
- **Token de 90 dias.** O token que a instalação recebe vale por 90 dias e não é renovado automaticamente. Depois disso, o cartão continua mostrando a conexão como ativa, mas as chamadas à nuvem falham com `Token expired`. Clique em **Desconectar** e depois em **Conectar** de novo. A instalação reutiliza o registro dela, então isso não conta para o limite de tentativas de conexão.
- **Funciona na hora.** O contêiner do app carrega a conexão por completo na inicialização seguinte. Até lá, o primeiro job que não encontra um provedor verifica a conexão de novo por conta própria, então clicar em **Executar** logo depois de conectar também funciona.
- **Armazenada no servidor.** A credencial da instalação nunca chega ao seu navegador. Ela é criptografada com a `NODARO_ENCRYPTION_KEY`, a mesma chave que protege as chaves de provedor coladas. Sem essa chave, a credencial é armazenada sem criptografia, e o app registra um aviso no log quando você se conecta.

## Escolher como a conexão é usada
Logo depois que você se conecta, uma caixa de diálogo pergunta **Como o nodaro.ai deve ser usado?** Ela abre depois do botão **Conectar** e depois que você cola uma chave de API. Fechá-la sem escolher aplica as opções pré-selecionadas.

- **nodaro para tudo** (pré-selecionada): todo recurso que a conexão cobre passa pelo Nodaro Cloud, com cobrança na conta conectada. Dentro dela, você escolhe quem prevalece quando também tem chaves próprias:
  - **nodaro primeiro** (pré-selecionada): as suas outras chaves de provedor são ignoradas para o que o Nodaro Cloud atende, e tudo é cobrado da sua conta do Nodaro Cloud.
  - **Minhas chaves primeiro**: os seus próprios provedores executam o que puderem, e o Nodaro Cloud cobre o resto.
- **Só os nós exclusivos do Nodaro**: só os [nós exclusivos do Nodaro](#the-nodaro-exclusive-nodes) usam a conexão. Todo o resto se comporta como se a conexão não existisse, com duas exceções descritas abaixo.

Para mudar a escolha, faça uma nova conexão: clique em **Alterar chave** no bloco nodaro.ai, ou em **Desconectar** e depois em **Conectar** no cartão da conexão. A caixa de diálogo abre de novo. Não há um controle separado. Scripts podem chamar `PUT /v1/nodaro-connect/prefs` com `{ "scope": "all" | "exclusives", "precedence": "nodaro" | "local" }` a partir de uma sessão logada do editor, como administrador na Business edition.

Duas regras mantêm o roteamento previsível:

- **As conexões antigas mantêm o roteamento delas.** As instalações conectadas antes de essa caixa de diálogo existir continuam executando tudo com **Minhas chaves primeiro** até alguém abrir a caixa de diálogo. O roteamento nunca muda em silêncio.
- **nodaro primeiro também cobre os nós de fornecedores.** Com **nodaro primeiro**, os nós de avatar, reiluminação, extração de dados da web e transcrição rodam pelo Nodaro Cloud mesmo quando você tem a chave desse fornecedor. Com **Minhas chaves primeiro**, a sua chave do fornecedor prevalece.

## Quais nós usam a conexão
### Nós que chamam um fornecedor diretamente
Alguns nós não passam pelo roteador de modelos: os handlers deles chamam um fornecedor. Estes são os nós:

- [Avatar de IA](https://nodaro.ai/docs/nodes/video/ai-avatar) e [Avatar cinematográfico](https://nodaro.ai/docs/nodes/video/cinematic-avatar)
- [Reiluminar e trocar](https://nodaro.ai/docs/nodes/video/relight-and-switch)
- [Extrair da web](https://nodaro.ai/docs/nodes/automate/web-scrape)
- Os nós de música do Suno, como o [**Gerar música com Suno** (Suno Create Music)](https://nodaro.ai/docs/nodes/audio/suno-create-music)
- [**Transcrever** (Transcribe)](https://nodaro.ai/docs/nodes/audio/transcribe) e a etapa de transcrição dos nós de legendas
- [**Gerar roteiro** (Generate Script)](https://nodaro.ai/docs/nodes/video/generate-script)

Em uma instalação conectada sem chave para esse fornecedor, o worker executa o job na mesma rota da sua conta do Nodaro Cloud. Depois, ele copia o resultado pronto para o seu próprio armazenamento e o registra como um job local. Os seletores de avatares e de vozes da HeyGen listam o catálogo do Nodaro Cloud da mesma forma.

| A sua escolha de roteamento | Com a chave do fornecedor | Sem a chave do fornecedor |
| --- | --- | --- |
| **nodaro primeiro** | Nodaro Cloud | Nodaro Cloud |
| **Minhas chaves primeiro** | A sua chave | Nodaro Cloud |
| **Só os nós exclusivos do Nodaro** | A sua chave | O nó não pode ser executado |

**O Suno e o Gerar roteiro ignoram a escolha de roteamento.** Com a sua própria chave, eles sempre rodam localmente: `KIE_API_KEY` para o Suno, e `KIE_API_KEY`, `ANTHROPIC_API_KEY` ou `GEMINI_API_KEY` para o Gerar roteiro. Sem nenhuma delas, eles sempre rodam pela conexão. Essas são as duas exceções em **Só os nós exclusivos do Nodaro**.

### Nós de texto
Os nós de texto chamam um modelo de texto diretamente. Entre eles estão o [**Prompt**](https://nodaro.ai/docs/nodes/automate/prompt), [**Escolher o melhor** (Choose Best)](https://nodaro.ai/docs/nodes/automate/choose-best), [**Descrever imagem** (Describe Image)](https://nodaro.ai/docs/nodes/image/describe-image), [**Verificar qualidade** (QA Check)](https://nodaro.ai/docs/nodes/automate/qa-check), [**Gráficos animados** (Motion Graphics)](https://nodaro.ai/docs/nodes/video/motion-graphics), [**Sobreposição Lottie** (Lottie Overlay)](https://nodaro.ai/docs/nodes/video/lottie-overlay), [**Título 3D** (3D Title)](https://nodaro.ai/docs/nodes/video/3d-title) e os analisadores dos seletores. Isso funciona da mesma forma quando o nó é executado sozinho ou dentro de um workflow.

- **Sem uma chave de modelo de texto**, ou seja, sem `KIE_API_KEY`, `ANTHROPIC_API_KEY` ou `GEMINI_API_KEY`, a requisição vai para a mesma rota da sua conta do Nodaro Cloud. A resposta é registrada como um job no seu próprio banco de dados, então ela aparece no seu histórico de execuções, e o ID do job funciona na sua instalação. Os IDs que só fazem sentido na sua instalação, como os IDs de workflow e de nó, nunca saem dela.
- **Com uma chave de modelo de texto**, o nó segue a sua escolha de roteamento: com **nodaro primeiro**, o Nodaro Cloud responde, e com **Minhas chaves primeiro**, a sua chave responde.

### Processamento local
Os nós de edição de vídeo e de áudio que rodam com o ffmpeg sempre rodam no seu servidor. Só a etapa de transcrição dos nós de legendas segue a mesma regra do [Transcrever](https://nodaro.ai/docs/nodes/audio/transcribe).

## Os nós exclusivos do Nodaro
Alguns nós são implementados só pelo Nodaro Cloud, como [**Gerar vídeo Pro** (Generate Video Pro)](https://nodaro.ai/docs/nodes/video/generate-video-pro), [**Editar vídeo Pro** (Edit Video Pro)](https://nodaro.ai/docs/nodes/video/edit-video-pro), [**Modificador de voz Pro** (Voice Changer Pro)](https://nodaro.ai/docs/nodes/audio/voice-changer-pro), [**Análise de vídeo** (Video Analysis)](https://nodaro.ai/docs/nodes/video/video-analysis) e [**Auditoria com IA** (AI Audit)](https://nodaro.ai/docs/nodes/video/ai-audit). Em uma instalação self-hosted, eles aparecem no editor com a marca **NODARO** e rodam pela sua conexão, com os mesmos recursos que no Nodaro Cloud. Isso inclui **Interromper e manter o que foi renderizado** e **Continuar** no Gerar vídeo Pro.

- **Não está conectado?** Os nós continuam aparecendo, e o nó mostra um botão **CONECTAR NODARO**. Uma execução falha com `503 nodaro_connection_required` e a mesma instrução. Um workflow que contém esses nós sempre é salvo: a verificação só acontece na hora da execução.
- **Cobrança.** As execuções são cobradas da conta do Nodaro Cloud conectada. Com o botão **Conectar**, vale o limite mensal da instalação. Com uma chave de API pessoal, a conta é usada diretamente, como ela é. Uma conta gratuita mantém os limites padrão e a marca d’água até a primeira compra, e nenhum limite por instalação se aplica.

O pipeline [**História → vídeo** (Story → Video)](https://nodaro.ai/docs/nodes/video/story-to-video) só está disponível no Nodaro Cloud. Ele é um mecanismo interativo, e não um nó que uma conexão consiga repassar.

## Ou usar uma chave de API, como qualquer outro provedor
O Nodaro Cloud também é um provedor no sentido comum, com um bloco em `/setup` como qualquer outro. Para pular o fluxo OAuth:

1. No app.nodaro.ai, abra **Configurações › Tokens de API** e crie um token de API pessoal.
2. Na sua instalação, cole-o no bloco **nodaro.ai**. Ele passa a valer na hora, mostra `key set (app)` e pode ser alterado ou removido como qualquer chave colada. A caixa de diálogo de roteamento abre depois de colar.

Para uma instalação sem interface (headless) ou para infraestrutura como código, defina-o no `.env`, em vez disso, e reinicie o contêiner do app:

```bash
NODARO_API_KEY=ndr_...
```

Nos dois casos, a geração roda pela conta do Nodaro Cloud dona do token, seguindo a sua escolha de roteamento.

| | Botão **Conectar** (OAuth) | Chave de API pessoal |
| --- | --- | --- |
| **Limite de gastos por instalação** | Sim, definido no Nodaro Cloud | Não |
| **Aparece em Instâncias conectadas** | Sim | Não |
| **Expira** | Depois de 90 dias | Nunca |
| **Revogar** | Desconectar no Nodaro Cloud | Exclua ou desative o token em **Configurações › Tokens de API** |

Um token de API pessoal não tem escopo, limite de gastos nem data de expiração, e uma conta pode ter no máximo 10. Ele pode gastar créditos, mas nunca pode comprar créditos, distribuir cotas nem administrar a conta. Quando uma instalação tem os dois, ela usa a conexão OAuth.

## Gerenciar as instalações conectadas no Nodaro Cloud
No app.nodaro.ai, abra **Cobrança › Instâncias conectadas**. O proprietário da conta vê todas as instalações conectadas, com o gasto de cada uma neste mês, e pode:

- **Definir um limite de gastos mensal** por instalação, de 100 a 1.000.000 créditos, ou deixá-lo vazio para não ter limite. Ele é salvo automaticamente. Acima do limite, as execuções da instalação falham com `402 instance_cap_reached`.
- **Desconectar** uma instalação. Os tokens dela param de funcionar na hora.

**Desconectar** na sua instalação só esquece o token local. A instalação mantém o registro, então o próximo **Conectar** o reutiliza. Para cortar o acesso por completo, desconecte a instalação no Nodaro Cloud.

**Configurações › Apps conectados**, no app.nodaro.ai, também lista cada instalação conectada, como **Instalação self-hosted**, ao lado dos outros apps com acesso à conta. **Revogar acesso** ali também encerra o acesso da instalação na hora.

## Quando a conexão falha
- **O Nodaro Cloud não está aceitando conexões ou não pode ser acessado.** O botão avisa isso ali mesmo, com `cloud_connect_unavailable` quando as conexões estão fechadas. Isso vem do Nodaro Cloud ou da sua rede. As suas próprias chaves de provedor, inclusive uma `NODARO_API_KEY`, continuam funcionando.
- **Tentativas de conexão não concluídas demais a partir deste endereço nas últimas 24 horas.** Cada clique em **Conectar** registra a instalação no Nodaro Cloud, e os registros que ninguém aprovou expiram depois de um dia. Depois de 10 deles a partir de um mesmo endereço em um dia, o Nodaro Cloud pausa esse endereço. Conclua a janela de consentimento que você já abriu, ou espere. Colar a sua própria chave de provedor funciona enquanto isso. Conectar de novo depois de um **Desconectar** não conta.
- **As chamadas à nuvem falham com `Token expired`.** O token de 90 dias expirou. Clique em **Desconectar** e depois em **Conectar**.
- **A tela de consentimento nunca volta para a sua instalação.** Defina `PUBLIC_URL` com o endereço real da sua instalação. O callback OAuth é registrado como `<PUBLIC_URL>/v1/nodaro-connect/callback`.

## Referência de configuração
| Variável | O que faz |
| --- | --- |
| `NODARO_CLOUD_URL` | O host do Nodaro Cloud ao qual se conectar, e para onde vão as chamadas com a `NODARO_API_KEY`. Padrão: `https://app.nodaro.ai`. Lida na inicialização. |
| `NODARO_API_KEY` | Um token de API pessoal do app.nodaro.ai, de **Configurações › Tokens de API**: o Nodaro Cloud como um provedor comum, sem fluxo OAuth. A conexão OAuth prevalece quando as duas existem. |
| `PUBLIC_URL` | O endereço público da sua instalação. O arquivo do Compose usa `http://localhost:3000` como padrão. Mantenha essa variável definida: quando ela está vazia, o valor volta para `https://app.nodaro.ai`, e a tela de consentimento nunca consegue voltar para a sua instalação. |
| `R2_SHARED_WITH_RELAY_TARGET` | Padrão: `false`. Defina `true` só quando `R2_PUBLIC_URL` apontar para o mesmo bucket em que o host do Nodaro Cloud grava. Os resultados da conexão passam, então, a ser usados ali mesmo, em vez de copiados. Eles nunca são apagados pela sua instalação e não contam para a cota de armazenamento dela. Só `true` e `1` ativam essa opção. |

`R2_SHARED_WITH_RELAY_TARGET` também muda o nó [**Salvar no armazenamento** (Save to Storage)](https://nodaro.ai/docs/nodes/publish/save-to-storage): quando a entrada dele já é um objeto do bucket, ele armazena uma referência em vez de uma cópia. Apagar o item da biblioteca dessa entrada apaga, então, o objeto para o qual o item salvo aponta. O arquivo do Compose não repassa essa variável do `.env`: adicione-a em `environment:` do serviço `nodaro`.

## Frequently asked questions

### O que eu ganho ao conectar uma instalação self-hosted ao Nodaro Cloud?

Os modelos de imagem, vídeo, fala e texto rodam com o seu saldo do Nodaro Cloud, sem chaves próprias. Os nós que precisam da chave de um fornecedor específico são executados sem ela, e os nós exclusivos do Nodaro, como o Gerar vídeo Pro, ficam disponíveis. O uso é cobrado em créditos da conta conectada.

### A conexão é por usuário ou por instalação?

Por instalação. Quem clica em Conectar vincula a instalação inteira à própria conta do Nodaro Cloud, e toda execução que usa a conexão é cobrada dessa conta.

### Por que as minhas execuções na nuvem falham com Token expired?

O token da conexão vale por 90 dias e não é renovado automaticamente. Clique em Desconectar e depois em Conectar de novo. A instalação reutiliza o registro dela, então reconectar é rápido.

### Posso usar uma chave de API em vez do botão Conectar?

Sim. Crie um token de API pessoal no app.nodaro.ai, em Configurações › Tokens de API, e cole-o no bloco nodaro.ai de /setup, ou defina NODARO_API_KEY no .env. Uma chave não tem limite de gastos por instalação e não aparece em Instâncias conectadas.

### Posso limitar quanto uma instalação conectada gasta?

Sim. No app.nodaro.ai, em Cobrança › Instâncias conectadas, defina um limite de gastos mensal por instalação, de 100 a 1.000.000 créditos. Acima do limite, as execuções falham com 402 instance_cap_reached.

### As minhas próprias chaves de provedor param de funcionar se o Nodaro Cloud estiver inacessível?

Não. As suas próprias chaves funcionam independentemente da conexão. Se o Nodaro Cloud não puder ser acessado ou não estiver aceitando conexões, o botão Conectar avisa isso, e todo o resto continua funcionando.