# Nodaro Cloud에 연결

> 셀프 호스팅 Nodaro를 Nodaro Cloud 계정에 연결하면 내 키 없이 표준 모델을 실행하고 Nodaro 전용 노드를 쓸 수 있습니다. 사용량은 크레딧으로 청구됩니다.

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

**Nodaro Cloud 연결**은 Nodaro Cloud를 내 키와 나란히 셀프 호스팅 설치의 모델 공급자 하나로 추가합니다. 그러면 표준 모델이 내 키 없이 Nodaro Cloud 잔액으로 실행되고, Nodaro Cloud에만 있는 Nodaro 전용 노드가 내 설치에서 작동합니다. 사용량은 연결된 Nodaro Cloud 계정에 크레딧으로 청구됩니다.

## 연결로 추가되는 것
- **클릭 한 번으로 시작.** 연결하면 Nodaro Cloud에 로그인하거나 계정을 새로 만듭니다. 새 계정은 첫 로그인 때 1,500크레딧을 한 번 받습니다. [무료 크레딧](https://nodaro.ai/docs/get-started/free-credits)을 참고하세요. 무료 계정의 출력물에는 첫 크레딧 구매 전까지 워터마크가 붙으며, 첫 구매로 모든 모델도 사용할 수 있게 됩니다.
- **키 없이 쓰는 표준 모델.** 이미지와 동영상 생성, 음성, 텍스트 모델이 Nodaro Cloud 잔액으로 실행됩니다.
- **업체 키가 필요한 노드.** [AI 아바타](https://nodaro.ai/docs/nodes/video/ai-avatar), [시네마틱 아바타](https://nodaro.ai/docs/nodes/video/cinematic-avatar), [조명 변경 및 교체](https://nodaro.ai/docs/nodes/video/relight-and-switch), [웹 스크래핑](https://nodaro.ai/docs/nodes/automate/web-scrape)이 각자의 키 없이 실행됩니다.
- **Nodaro 전용 노드.** [Nodaro 전용 노드](#the-nodaro-exclusive-nodes)를 참고하세요.
- 연결된 설치의 사용량에는 **일일 지출 한도가 없습니다**.

생성 작업 중 얼마만큼을 연결로 처리할지는 내가 정합니다. [연결 사용 방식 선택](#choose-how-the-connection-is-used)을 참고하세요.

## 내 설치 연결
관련된 계정은 딱 두 개입니다. 내 설치의 자체 데이터베이스에 있는 **서버 로그인**과 **Nodaro Cloud 계정**입니다.

### 연결 시작
내 설치에서 `/setup`을 열고 2단계에서 **nodaro.ai 연결**을 클릭하세요. 또는 **연동**을 열고 **nodaro.ai**를 찾아 **연결**을 클릭하세요.

### Nodaro Cloud에서 승인
브라우저에 Nodaro Cloud 동의 화면이 열립니다. 로그인하거나 가입한 뒤 승인하세요. 설치는 자체 OAuth 자격 증명으로 스스로를 등록하고, 생성에 필요한 범위만 정확히 요청합니다: `assets:write workflows:execute jobs:read credits:read`.

그 브라우저가 이미 Nodaro Cloud에 로그인되어 있으면, 화면에 연결하려는 계정이 표시됩니다. 이 계정은 Nodaro Cloud 계정이며 내 서버 로그인과는 관계가 없습니다. 다른 계정을 연결하려면 **다른 계정 사용**을 클릭하세요.

### 내 설치로 돌아오기
연결이 활성화된 상태로 내 설치로 돌아옵니다. 카드에 실시간 Nodaro Cloud 잔액이 표시됩니다. 그다음 연결을 어떻게 사용할지 묻는 대화 상자가 열립니다.

- **설치당 연결 하나.** 연결은 사용자가 아니라 설치에 속합니다. **연결**을 클릭한 사람이 설치 전체를 자신의 Nodaro Cloud 계정에 연결합니다.
- **90일 토큰.** 설치가 받는 토큰은 90일 동안 유효하며 자동으로 갱신되지 않습니다. 그 뒤에는 카드에 여전히 연결됨으로 표시되지만 클라우드 호출이 `Token expired`로 실패합니다. **연결 해제**를 클릭한 뒤 다시 **연결**을 클릭하세요. 설치가 기존 등록을 재사용하므로, 연결 시도 횟수 제한에 포함되지 않습니다.
- **바로 작동.** 앱 컨테이너는 다음 시작 때 연결을 완전히 불러옵니다. 그 전까지는 공급자를 찾지 못한 첫 작업이 스스로 연결을 다시 확인하므로, 연결 직후의 **실행**도 작동합니다.
- **서버에 저장.** 설치의 자격 증명은 브라우저에 절대 전달되지 않습니다. 붙여 넣은 공급자 키를 보호하는 것과 같은 키인 `NODARO_ENCRYPTION_KEY`로 암호화됩니다. 이 키가 없으면 자격 증명은 암호화되지 않은 채 저장되며, 연결할 때 앱이 경고를 기록합니다.

## 연결 사용 방식 선택
연결 직후 **nodaro.ai를 어떻게 사용하시겠습니까?** 대화 상자가 열립니다. 이 대화 상자는 **연결** 버튼을 누른 뒤와 API 키를 붙여 넣은 뒤에 열립니다. 선택하지 않고 닫으면 미리 선택된 옵션이 적용됩니다.

- **모두 nodaro로**(미리 선택됨): 연결이 지원하는 모든 기능이 Nodaro Cloud를 통해 실행되고 연결된 계정에 청구됩니다. 이 안에서 내 키도 있을 때 어느 쪽을 우선할지 고릅니다.
  - **nodaro 우선**(미리 선택됨): Nodaro Cloud가 처리하는 기능에서는 다른 공급자 키를 무시하고, 모든 사용량을 Nodaro Cloud 계정에 청구합니다.
  - **내 키 우선**: 내 공급자가 실행할 수 있는 것을 실행하고, Nodaro Cloud가 빈틈을 채웁니다.
- **Nodaro 전용 노드만**: [Nodaro 전용 노드](#the-nodaro-exclusive-nodes)만 연결을 사용합니다. 아래에 설명한 두 가지 예외를 빼면, 나머지는 모두 연결이 없는 것처럼 작동합니다.

선택을 바꾸려면 새로 연결하세요. nodaro.ai 타일에서 **키 변경**을 클릭하거나, 연결 카드에서 **연결 해제**를 클릭한 뒤 **연결**을 클릭하면 대화 상자가 다시 열립니다. 별도의 설정 항목은 없습니다. 스크립트에서는 로그인한 편집기 세션에서, Business 에디션이라면 관리자로서 `{ "scope": "all" | "exclusives", "precedence": "nodaro" | "local" }`와 함께 `PUT /v1/nodaro-connect/prefs`를 호출할 수 있습니다.

두 가지 규칙 덕분에 라우팅을 예측할 수 있습니다.

- **이전 연결은 기존 라우팅을 유지합니다.** 이 대화 상자가 생기기 전에 연결한 설치는 누군가 대화 상자를 열 때까지 모든 것을 **내 키 우선**으로 계속 실행합니다. 라우팅은 조용히 바뀌지 않습니다.
- **nodaro 우선은 업체 노드에도 적용됩니다.** **nodaro 우선**에서는 아바타, 조명 변경, 웹 스크래핑, 음성 텍스트 변환 노드가 해당 업체의 키가 있어도 Nodaro Cloud를 통해 실행됩니다. **내 키 우선**에서는 내 업체 키가 우선합니다.

## 연결을 사용하는 노드
### 업체를 직접 호출하는 노드
일부 노드는 모델 라우터를 거치지 않고 핸들러가 업체를 직접 호출합니다. 이런 노드는 다음과 같습니다.

- [AI 아바타](https://nodaro.ai/docs/nodes/video/ai-avatar)와 [시네마틱 아바타](https://nodaro.ai/docs/nodes/video/cinematic-avatar)
- [조명 변경 및 교체](https://nodaro.ai/docs/nodes/video/relight-and-switch)
- [웹 스크래핑](https://nodaro.ai/docs/nodes/automate/web-scrape)
- [Suno 음악 생성](https://nodaro.ai/docs/nodes/audio/suno-create-music) 같은 Suno 음악 노드
- [음성 텍스트 변환](https://nodaro.ai/docs/nodes/audio/transcribe), 그리고 자막 노드의 음성 텍스트 변환 단계
- [대본 생성](https://nodaro.ai/docs/nodes/video/generate-script)

해당 업체의 키가 없는 연결된 설치에서는 워커가 Nodaro Cloud 계정의 같은 경로에서 작업을 실행합니다. 그런 다음 완성된 결과를 내 스토리지로 복사하고 로컬 작업으로 기록합니다. HeyGen 아바타와 보이스 피커도 같은 방식으로 Nodaro Cloud의 카탈로그를 보여 줍니다.

| 내 라우팅 선택 | 업체 키가 있을 때 | 업체 키가 없을 때 |
| --- | --- | --- |
| **nodaro 우선** | Nodaro Cloud | Nodaro Cloud |
| **내 키 우선** | 내 키 | Nodaro Cloud |
| **Nodaro 전용 노드만** | 내 키 | 노드를 실행할 수 없음 |

**Suno와 대본 생성은 라우팅 선택을 무시합니다.** 내 키가 있으면 항상 로컬에서 실행됩니다. Suno는 `KIE_API_KEY`, 대본 생성은 `KIE_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` 중 하나를 씁니다. 키가 없으면 항상 연결로 실행됩니다. 이 두 노드가 **Nodaro 전용 노드만**에서의 두 가지 예외입니다.

### 텍스트 노드
[텍스트 생성 - 모든 LLM](https://nodaro.ai/docs/nodes/automate/prompt), [최적 선택](https://nodaro.ai/docs/nodes/automate/choose-best), [이미지 설명](https://nodaro.ai/docs/nodes/image/describe-image), [품질 검사](https://nodaro.ai/docs/nodes/automate/qa-check), [모션 그래픽](https://nodaro.ai/docs/nodes/video/motion-graphics), [Lottie 오버레이](https://nodaro.ai/docs/nodes/video/lottie-overlay), [3D 타이틀](https://nodaro.ai/docs/nodes/video/3d-title) 같은 텍스트 노드와 피커 분석기는 텍스트 모델을 직접 호출합니다. 노드를 단독으로 실행할 때와 워크플로 안에서 실행할 때 똑같이 작동합니다.

- **텍스트 모델 키가 없으면**, 즉 `KIE_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`가 모두 없으면 요청이 Nodaro Cloud 계정의 같은 경로로 갑니다. 응답은 내 데이터베이스에 작업으로 기록되므로 실행 기록에 나타나며, 그 작업 ID는 내 설치에서 작동합니다. 워크플로 ID와 노드 ID처럼 내 설치에서만 의미가 있는 ID는 설치 밖으로 나가지 않습니다.
- **텍스트 모델 키가 있으면**, 노드는 내 라우팅 선택을 따릅니다. **nodaro 우선**에서는 Nodaro Cloud가, **내 키 우선**에서는 내 키가 응답합니다.

### 로컬 처리
ffmpeg 기반으로 실행되는 동영상 및 오디오 편집 노드는 항상 내 서버에서 실행됩니다. 자막 노드의 음성 텍스트 변환 단계만 [음성 텍스트 변환](https://nodaro.ai/docs/nodes/audio/transcribe)과 같은 규칙을 따릅니다.

## Nodaro 전용 노드
[동영상 생성 Pro](https://nodaro.ai/docs/nodes/video/generate-video-pro), [동영상 편집 Pro](https://nodaro.ai/docs/nodes/video/edit-video-pro), [보이스 체인저 Pro](https://nodaro.ai/docs/nodes/audio/voice-changer-pro), [동영상 분석](https://nodaro.ai/docs/nodes/video/video-analysis), [AI 검수](https://nodaro.ai/docs/nodes/video/ai-audit) 같은 일부 노드는 Nodaro Cloud에만 구현되어 있습니다. 셀프 호스팅 설치에서는 이 노드가 편집기에 **NODARO** 표시와 함께 나타나며, 내 연결을 통해 Nodaro Cloud와 같은 기능으로 실행됩니다. 여기에는 동영상 생성 Pro의 **중지하고 렌더링된 부분 유지**와 **계속**도 포함됩니다.

- **연결하지 않았나요?** 노드는 그대로 나타나며, 노드에 **Nodaro 연결** 버튼이 표시됩니다. 실행하면 같은 안내와 함께 `503 nodaro_connection_required`로 실패합니다. 이 노드가 들어 있는 워크플로는 항상 저장됩니다. 확인은 실행할 때만 이루어집니다.
- **청구.** 실행은 연결된 Nodaro Cloud 계정에 청구됩니다. **연결** 버튼으로 연결했다면 설치의 월 한도가 적용됩니다. 개인 API 키를 쓰면 계정이 그 계정 자체로 사용됩니다. 무료 계정은 첫 구매 전까지 표준 제한과 워터마크가 유지되며, 설치별 한도는 적용되지 않습니다.

[스토리 → 동영상](https://nodaro.ai/docs/nodes/video/story-to-video) 파이프라인은 Nodaro Cloud에서만 사용할 수 있습니다. 연결이 중계할 수 있는 노드가 아니라 대화형 엔진이기 때문입니다.

## 다른 공급자처럼 API 키 사용
Nodaro Cloud는 일반적인 의미의 공급자이기도 하며, 다른 공급자처럼 `/setup`에 타일이 있습니다. OAuth 흐름을 건너뛰려면 다음과 같이 하세요.

1. app.nodaro.ai에서 **설정 › API 토큰**을 열고 개인 API 토큰을 만듭니다.
2. 내 설치에서 **nodaro.ai** 타일에 토큰을 붙여 넣습니다. 즉시 적용되고 `key set (app)`이 표시되며, 붙여 넣은 다른 키처럼 바꾸거나 삭제할 수 있습니다. 붙여 넣은 뒤 라우팅 대화 상자가 열립니다.

헤드리스 설치나 코드형 인프라에서는 대신 `.env`에 설정하고 앱 컨테이너를 재시작하세요.

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

어느 방법이든 생성은 내 라우팅 선택에 따라, 토큰을 소유한 Nodaro Cloud 계정을 통해 실행됩니다.

| | **연결** 버튼(OAuth) | 개인 API 키 |
| --- | --- | --- |
| **설치별 지출 한도** | 예, Nodaro Cloud에서 설정 | 아니요 |
| **연결된 인스턴스에 표시** | 예 | 아니요 |
| **만료** | 90일 후 | 없음 |
| **취소** | Nodaro Cloud에서 연결 해제 | **설정 › API 토큰**에서 삭제하거나 비활성화 |

개인 API 토큰에는 범위도, 지출 한도도, 만료도 없으며, 계정 하나에 최대 10개까지 만들 수 있습니다. 크레딧을 쓸 수는 있지만, 크레딧을 구매하거나 사용 한도를 배정하거나 계정을 관리할 수는 없습니다. 설치에 둘 다 있으면 OAuth 연결을 사용합니다.

## Nodaro Cloud에서 연결된 설치 관리
app.nodaro.ai에서 **결제 › 연결된 인스턴스**를 여세요. 계정 소유자는 연결된 모든 설치와 이번 달 지출을 보고 다음을 할 수 있습니다.

- 설치마다 100~1,000,000크레딧 사이의 **월 지출 한도를 설정**하거나, 비워 두어 한도를 없앨 수 있습니다. 자동으로 저장됩니다. 한도를 넘으면 그 설치의 실행이 `402 instance_cap_reached`로 실패합니다.
- 설치를 **연결 해제**할 수 있습니다. 그 설치의 토큰은 즉시 작동을 멈춥니다.

내 설치에서 **연결 해제**를 누르면 로컬 토큰만 지워집니다. 설치는 등록을 유지하므로 다음 **연결** 때 그 등록을 재사용합니다. 접근을 완전히 끊으려면 Nodaro Cloud에서 연결을 해제하세요.

app.nodaro.ai의 **설정 › 연결된 앱**에도 연결된 각 설치가 계정에 접근할 수 있는 다른 앱과 함께 **셀프 호스팅 설치**로 표시됩니다. 그곳에서 **접근 취소**를 눌러도 설치의 접근이 즉시 끝납니다.

## 연결에 실패할 때
- **Nodaro Cloud가 연결을 받지 않거나 연결할 수 없습니다.** 버튼 자리에 그 사실이 표시되며, 연결이 닫혀 있을 때는 `cloud_connect_unavailable`이 함께 표시됩니다. 원인은 Nodaro Cloud나 내 네트워크에 있습니다. `NODARO_API_KEY`를 포함한 내 공급자 키는 계속 작동합니다.
- **지난 24시간 동안 이 주소에서 완료되지 않은 연결 시도가 너무 많습니다.** **연결**을 클릭할 때마다 설치가 Nodaro Cloud에 등록되며, 아무도 승인하지 않은 등록은 하루 뒤 만료됩니다. 한 주소에서 하루에 이런 등록이 10개가 되면 Nodaro Cloud가 그 주소를 일시 중지합니다. 이미 열어 둔 동의 창에서 승인을 마치거나 기다리세요. 그동안에도 내 공급자 키를 붙여 넣는 방법은 작동합니다. **연결 해제** 후 다시 연결하는 것은 횟수에 포함되지 않습니다.
- **클라우드 호출이 `Token expired`로 실패합니다.** 90일 토큰이 만료되었습니다. **연결 해제**를 클릭한 뒤 **연결**을 클릭하세요.
- **동의 화면이 내 설치로 돌아오지 않습니다.** `PUBLIC_URL`을 내 설치의 실제 주소로 설정하세요. OAuth 콜백은 `<PUBLIC_URL>/v1/nodaro-connect/callback`으로 등록됩니다.

## 구성 레퍼런스
| 변수 | 역할 |
| --- | --- |
| `NODARO_CLOUD_URL` | 연결할 Nodaro Cloud 호스트이자, `NODARO_API_KEY`를 쓰는 호출이 가는 곳입니다. 기본값은 `https://app.nodaro.ai`입니다. 부팅할 때 읽습니다. |
| `NODARO_API_KEY` | app.nodaro.ai의 **설정 › API 토큰**에서 만든 개인 API 토큰입니다. OAuth 흐름 없이 Nodaro Cloud를 일반 공급자로 씁니다. 둘 다 있으면 OAuth 연결이 우선합니다. |
| `PUBLIC_URL` | 내 설치의 공개 주소입니다. Compose 파일의 기본값은 `http://localhost:3000`입니다. 반드시 설정해 두세요. 비어 있으면 `https://app.nodaro.ai`로 대체되어, 동의 화면이 내 설치로 돌아올 수 없습니다. |
| `R2_SHARED_WITH_RELAY_TARGET` | 기본값은 `false`입니다. `R2_PUBLIC_URL`이 Nodaro Cloud 호스트가 쓰는 버킷과 같은 버킷을 가리킬 때만 `true`로 설정하세요. 그러면 연결에서 받은 결과를 복사하지 않고 그 자리에서 사용합니다. 이 결과는 내 설치가 삭제하지 않으며 스토리지 할당량에도 포함되지 않습니다. `true`와 `1`만 이 설정을 켭니다. |

`R2_SHARED_WITH_RELAY_TARGET`은 [저장소에 저장](https://nodaro.ai/docs/nodes/publish/save-to-storage) 노드의 동작도 바꿉니다. 입력이 이미 버킷 안의 객체이면 사본 대신 참조를 저장합니다. 그러면 그 입력의 라이브러리 항목을 삭제할 때, 저장된 항목이 가리키는 객체도 삭제됩니다. Compose 파일은 이 변수를 `.env`에서 전달하지 않으므로, `nodaro` 서비스의 `environment:` 아래에 추가하세요.

## 자주 묻는 질문

### 셀프 호스팅 설치를 Nodaro Cloud에 연결하면 무엇을 할 수 있나요?

이미지, 동영상, 음성, 텍스트 모델이 내 키 없이 Nodaro Cloud 잔액으로 실행되고, 특정 업체 키가 필요한 노드도 그 키 없이 실행되며, 동영상 생성 Pro 같은 Nodaro 전용 노드를 쓸 수 있게 됩니다. 사용량은 연결된 계정에 크레딧으로 청구됩니다.

### 연결은 사용자별인가요, 설치별인가요?

설치별입니다. 연결을 클릭한 사람이 설치 전체를 자신의 Nodaro Cloud 계정에 연결하며, 연결을 사용하는 모든 실행은 그 계정에 청구됩니다.

### 클라우드 실행이 Token expired로 실패하는 이유는 무엇인가요?

연결 토큰은 90일 동안 유효하며 자동으로 갱신되지 않습니다. 연결 해제를 클릭한 뒤 다시 연결을 클릭하세요. 설치가 기존 등록을 재사용하므로 다시 연결하는 데 오래 걸리지 않습니다.

### 연결 버튼 대신 API 키를 써도 되나요?

네. app.nodaro.ai의 설정 › API 토큰에서 개인 API 토큰을 만들어 /setup의 nodaro.ai 타일에 붙여 넣거나, .env에 NODARO_API_KEY를 설정하세요. 키에는 설치별 지출 한도가 없으며 연결된 인스턴스에 표시되지 않습니다.

### 연결된 설치가 쓰는 금액을 제한할 수 있나요?

네. app.nodaro.ai의 결제 › 연결된 인스턴스에서 설치마다 100~1,000,000크레딧 사이의 월 지출 한도를 설정하세요. 한도를 넘으면 실행이 402 instance_cap_reached로 실패합니다.

### Nodaro Cloud에 연결할 수 없으면 내 공급자 키도 작동하지 않나요?

아니요. 내 키는 연결과 별개로 작동합니다. Nodaro Cloud에 연결할 수 없거나 Nodaro Cloud가 연결을 받지 않는 경우, 연결 버튼이 그 사실을 알려 주고 나머지는 계속 실행됩니다.