# 공급자 키

> 셀프 호스팅 Nodaro에 /setup이나 .env로 모델 공급자 키를 추가하고, 각 키로 실행되는 노드를 확인하고, 공급자 트래픽을 내 프록시로 보내는 방법을 알아보세요.

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

**공급자 키**는 셀프 호스팅 Nodaro가 AI 모델을 호출할 수 있게 해 주는 API 키입니다. 앱에 붙여 넣거나 환경 변수로 설정할 수 있으며, 두 방법을 동시에 쓸 수 있습니다. 키 대신, 또는 키와 함께 설치를 Nodaro Cloud 계정에 연결할 수도 있습니다. [Nodaro Cloud에 연결](https://nodaro.ai/docs/self-hosting/cloud-connect)을 참조하세요.

## 키를 추가하는 두 가지 방법
| 방법 | 키가 있는 곳 | 적용 시점 | 바꿀 수 있는 사람 |
| --- | --- | --- | --- |
| **앱에 붙여 넣기**: `/setup`의 **설치 상태** 섹션 또는 **연동 › 모델 공급자** | 인스턴스 키로 암호화된 내 데이터베이스. 어떤 경로도 키를 반환하지 않습니다. | 즉시. API는 바로 사용하고, 워커는 약 30초 안에 읽습니다. 재시작이 필요 없습니다. | Community: 로그인한 모든 사용자. Business: 관리자. |
| **환경 변수로 설정**: `.env` 또는 플랫폼의 변수 | 내 환경 | 다음 시작 시 | 서버를 관리하는 사람 |

키를 붙여 넣은 직후의 **실행**도 작동합니다. 공급자를 찾지 못한 노드는 실패하기 전에 키를 한 번 다시 읽습니다.

키를 붙여 넣으려면 항상 앱에 로그인한 세션이 필요합니다. API 토큰이나 앱 토큰으로는 키를 절대 바꿀 수 없습니다. `/setup`의 상태 카드는 로그인 없이 볼 수 있지만, 그곳에서 키를 저장하려면 로그인해야 합니다. 먼저 1단계 **서버 로그인 계정 만들기**를 완료하세요.

## 우선하는 키
**환경 변수가 우선합니다.** 환경 변수로 설정한 키는 화면에서 읽기 전용입니다. 그 타일에는 `set (env)`(환경 변수에서 설정됨)이 표시되고, 제거해야 할 변수 이름이 나옵니다. 붙여 넣은 키는 해당 공급자의 키가 환경 변수에 없을 때만 쓰입니다.

## 타일에서 키 관리
`.env`에서 온 키를 포함해 모든 공급자 타일은 실행 중에 관리할 수 있습니다. 변경 사항은 재시작 없이 적용됩니다.

- **붙여 넣은 키**에는 `set (app)`(앱에서 설정됨)이 표시되고, **nodaro.ai** 타일에는 `key set (app)`이 표시됩니다. 언제든지 **키 변경** 또는 **제거**를 클릭하세요.
- **`.env`의 키**는 그 자리에서 편집할 수 없습니다. **.env 키 교체**는 파일을 편집하지 않고, 환경 변수의 키보다 우선하는 키를 앱에 저장합니다. 또는 `.env`에서 키를 제거하고 재시작하세요.
- **비활성화**는 다시 활성화할 때까지 공급자를 멈춥니다. 키가 `.env`에서 왔든 붙여 넣은 것이든 마찬가지입니다. 예를 들어 생성을 Nodaro Cloud 연결 같은 다른 공급자로 옮길 때 쓰세요.
- **누락됨**은 공급자에 키가 없다는 뜻입니다. **비활성화됨**은 내가 공급자를 껐다는 뜻입니다.

각 타일에는 그 키로 실행되는 기능과 키를 받는 곳이 나와 있습니다.

## 모든 공급자 키
| 변수 | 실행되는 기능 |
| --- | --- |
| `NODARO_API_KEY` | 공급자로서의 Nodaro Cloud입니다. app.nodaro.ai › **설정 › API 토큰**에서 만든 개인 API 토큰이며, 해당 계정으로 청구됩니다. [Nodaro Cloud에 연결](https://nodaro.ai/docs/self-hosting/cloud-connect#or-use-an-api-key-like-any-other-provider)을 참조하세요. |
| `KIE_API_KEY` | 가장 넓은 모델 범위입니다. Suno 음악 노드를 포함한 이미지, 동영상, 오디오, 텍스트 모델을 제공합니다. |
| `REPLICATE_API_TOKEN` | 자체 카탈로그가 있는 대체 공급자이며, Flux 2 모델을 포함합니다. |
| `ANTHROPIC_API_KEY` | 텍스트 노드용 Claude 모델을 직접 호출합니다. |
| `GEMINI_API_KEY` | Gemini 모델을 직접 호출합니다. Google AI Studio 키입니다. [Gemini 모델](#gemini-models)을 참조하세요. |
| `ELEVENLABS_API_KEY` | 음성, 보이스, 더빙, 보이스 체인저, 강제 정렬입니다. |
| `FAL_KEY` | 선택 사항입니다. [Sync Lipsync v3](https://nodaro.ai/docs/models/video/sync-lipsync-v3) 같은 모델에 쓰입니다. 이 키가 없으면 해당 모델을 쓸 수 없고, 다른 것은 바뀌지 않습니다. |

### 특정 노드에서 쓰는 키
해당 노드를 쓰지 않는다면 비워 두세요. 연결된 설치에서는 키가 비어 있을 때 이 노드들이 Nodaro Cloud를 통해 실행됩니다.

| 변수 | 노드 |
| --- | --- |
| `HEYGEN_API_KEY` | [AI 아바타](https://nodaro.ai/docs/nodes/video/ai-avatar)와 [시네마틱 아바타](https://nodaro.ai/docs/nodes/video/cinematic-avatar) |
| `BEEBLE_API_KEY` | [조명 변경 및 교체](https://nodaro.ai/docs/nodes/video/relight-and-switch) |
| `APIFY_API_TOKEN` | [웹 스크래핑](https://nodaro.ai/docs/nodes/automate/web-scrape), [사이트 캡처](https://nodaro.ai/docs/nodes/automate/site-capture)와 [Meta 광고](https://nodaro.ai/docs/nodes/automate/meta-ads) |

`GEMINI_API_KEY`는 `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`과 다릅니다. 이 두 값은 YouTube 게시 등에 쓰는 Google OAuth 앱의 값입니다. [소셜 네트워크 앱](https://nodaro.ai/docs/self-hosting/configuration#social-network-apps)을 참조하세요.

## 키와 Nodaro Cloud 연결
- **연결 하나로 모든 타일이 해결됩니다.** 연결된 설치에서는 이미지, 동영상, 음성, 텍스트 모델과 아바타, 조명 변경 및 교체, 웹 스크래핑이 내 Nodaro Cloud 계정을 통해 실행됩니다. 해당 공급자를 직접 호출하려는 경우에만 키를 붙여 넣으세요.
- **우선순위는 내가 정합니다.** 연결할 때 대화 상자에서 Nodaro Cloud가 먼저 모든 것을 실행할지, 내 키가 먼저 실행할지 묻습니다. [연결 사용 방식 선택](https://nodaro.ai/docs/self-hosting/cloud-connect#choose-how-the-connection-is-used)을 참조하세요.
- **OAuth 연결이 `NODARO_API_KEY`보다 우선합니다.** 설치에 둘 다 있으면 연결을 쓰고 키는 무시합니다.

## Gemini 모델
Gemini 모델은 두 가지 방식으로 실행할 수 있습니다. `GEMINI_API_KEY`가 없으면 `KIE_API_KEY`로 실행됩니다. 이 키가 있으면 다음과 같습니다.

- **Gemini 3.1 Pro**는 먼저 Google에서 직접 실행되고, `KIE_API_KEY`가 대체 경로가 됩니다.
- **Gemini Flash 모델**은 `KIE_API_KEY`에 그대로 머물고, 그것이 실패할 때만 `GEMINI_API_KEY`를 씁니다.

설정하기 전에 알아 둘 점이 두 가지 있습니다.

- **비용.** Google은 직접 경로를 자체 토큰당 가격으로 청구하며, 같은 모델을 `KIE_API_KEY`로 쓸 때보다 비쌀 수 있습니다. 사용량이 많은 모델을 옮기기 전에 Google의 현재 가격을 확인하세요.
- **미디어.** Google의 API는 임의의 URL을 가져올 수 없습니다. Nodaro는 각 이미지, 동영상, 오디오 레퍼런스를 내려받아, 작으면 인라인 데이터로, 크면 Gemini Files API로 보냅니다. Files API는 파일을 48시간 동안 보관합니다.

## 내 프록시로 공급자 트래픽 보내기
두 공급자는 키뿐 아니라 호스트도 바꿀 수 있습니다.

| 변수 | 기본값 | 옮겨지는 것 |
| --- | --- | --- |
| `KIE_API_BASE_URL` | 공급자 자체의 API 호스트 | `KIE_API_KEY`로 하는 모든 호출: 미디어 생성 **그리고** 이 키로 실행되는 Claude와 Gemini 텍스트 트래픽 |
| `ELEVENLABS_BASE_URL` | `https://api.elevenlabs.io` | 모든 ElevenLabs 호출: 텍스트 음성 변환, 음성 텍스트 변환, 보이스, 클로닝, 더빙, 강제 정렬 |

둘 다 설정하지 않으면 아무것도 바뀌지 않습니다. 하나를 설정하면 Nodaro는 대신 내 호스트와 통신합니다. 흔한 이유는 실제 키를 프록시에만 두는 키 보관, 모든 외부 생성 요청의 감사 로그, 지역별 라우팅입니다.

프록시는 투명해야 합니다. Nodaro는 출처만 바꾸므로 경로, 요청 본문, 응답 본문이 같아야 합니다. 끝의 슬래시는 제거되므로 `https://proxy.example.com/models/`와 `https://proxy.example.com/models`는 똑같이 동작합니다.

**KIE_API_BASE_URL은 텍스트 모델 트래픽도 옮깁니다:** 
프롬프트 개선, 대본 생성 등 텍스트 기능 뒤의 Claude와 Gemini 트래픽도 같은 호스트를 거칩니다. 프록시는 미디어 API뿐 아니라 다음 경로도 전달해야 합니다.

- `/api/v1/...`: 작업, 폴링, 잔액 확인
- `/claude/v1/messages`
- `/<family>/v1/chat/completions`
- `/<family>/v1/responses`
- `/client/v1/userRecord/...`: 크레딧 조회

미디어 경로만 전달하는 프록시를 쓰면 이미지와 동영상은 계속 작동하지만 모든 텍스트 기능이 실패합니다.

`ANTHROPIC_API_KEY`와 `GEMINI_API_KEY`는 프록시의 영향을 받지 않습니다. 이 키를 쓰면 해당 모델은 Anthropic과 Google을 직접 호출합니다.

## 키 작동 확인
- **편집기에서.** Welcome Demo를 열고 **장면 이미지** 노드에서 **실행**을 클릭하세요.
- **명령줄에서.** `--keyed`로 프로브를 실행하세요. `KIE_API_KEY` 또는 `REPLICATE_API_TOKEN`에 맞는 가장 저렴한 모델로 실제 생성을 한 번 하고, 미디어가 내 스토리지에 저장되는지 확인합니다.

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

`Missing API key`로 실패하는 노드는 키가 없는 공급자를 호출하고 있습니다. `/setup`이나 `.env`에 그 공급자의 키를 추가하세요.

## 암호화 키
붙여 넣은 키에는 인스턴스 암호화 키 `NODARO_ENCRYPTION_KEY`가 필요합니다. 번들된 Compose 스택은 첫 부팅 때 이 키를 생성합니다. 키가 없으면 타일에 **누락됨**이 표시되고, `/setup`에 해결 방법과 함께 빨간색 **암호화** 카드가 나타납니다. 환경 변수로 설정한 키는 계속 작동합니다. [설치](https://nodaro.ai/docs/self-hosting/install#2-generate-the-internal-secrets)를 참조하세요.

## 자주 묻는 질문

### 셀프 호스팅 Nodaro에서 공급자 키는 어디에 추가하나요?

/setup의 설치 상태 섹션이나, 앱의 연동 › 모델 공급자에 붙여 넣으세요. 또는 .env에 설정하고 docker compose up -d를 실행하세요. 붙여 넣은 키는 재시작 없이 바로 적용됩니다.

### .env의 키와 화면에 붙여 넣은 키 중 무엇이 우선하나요?

환경 변수의 키가 우선합니다. 그 타일에는 “set (env)”(환경 변수에서 설정됨)이 표시되며, 그 자리에서 편집할 수 없습니다. .env에서 키를 제거하고 재시작하거나, 타일의 .env 키 교체로 화면에서 덮어쓰세요.

### 공급자 키는 누가 바꿀 수 있나요?

Community Edition에서는 로그인한 모든 사용자가 바꿀 수 있습니다. 운영자 한 명을 위한 에디션이기 때문입니다. Business 에디션에서는 관리자만 바꿀 수 있습니다. API 토큰과 앱 토큰으로는 절대 바꿀 수 없습니다.

### 붙여 넣은 키는 어디에 저장되나요?

내 데이터베이스에 인스턴스 암호화 키를 사용한 AES-256-GCM으로 암호화되어 저장됩니다. 어떤 경로도 키를 반환하지 않습니다. 암호화 키가 없으면 타일에 누락됨이 표시되고, /setup에 빨간색 암호화 카드가 나타납니다.

### 이미지와 동영상은 되는데 모든 텍스트 기능이 실패하는 이유는 무엇인가요?

KIE_API_BASE_URL을 프록시로 설정했다면, 프록시가 미디어 API뿐 아니라 텍스트 모델 경로도 전달해야 합니다. 미디어 경로만 전달하는 프록시는 텍스트 모델을 쓰는 모든 기능을 망가뜨립니다.