n8n

OpenAI 자격 증명의 Base URL 필드에 /v1을 유지한 https://api.kunavo.com/v1을 입력하면 n8n 워크플로의 모든 OpenAI Chat Model이 Kunavo를 사용합니다. 모델 노드 자체에는 엔드포인트 필드가 없습니다

Credentials  →  Create credential  →  OpenAI
  API Key                      sk-kn-...
  Organization ID (optional)   leave empty
  Base URL                     https://api.kunavo.com/v1     <- keep the /v1

Workflow  →  AI Agent or Basic LLM Chain  →  Chat Model: OpenAI Chat Model
  Credential to connect with   the OpenAI credential above
  Model                        ID mode:  claude-sonnet-5
  Use Responses API            on   → POST /v1/responses
                               off  → POST /v1/chat/completions

단계별 안내

1. /app/keys에서 키를 생성해 복사하세요. 키는 한 번만 표시됩니다.
2. n8n에서 OpenAI 유형의 자격 증명을 만듭니다. API Key에 키를 입력하고 Organization ID (optional)는 비워 둡니다. 기본 https://api.openai.com/v1 값을 Base URL 필드에서 https://api.kunavo.com/v1로 바꾼 다음 저장합니다.
3. AI Agent 또는 Basic LLM Chain 노드를 추가하고, 이 자격 증명을 사용하는 OpenAI Chat Model 하위 노드를 연결합니다. Model 필드를 From List에서 ID로 바꾸고 GET /v1/models에 표시된 형식 그대로 ID를 입력합니다. 예를 들면 claude-sonnet-5입니다. 목록에서 선택해도 되지만, ID를 직접 입력하면 워크플로를 읽기 쉽습니다.
4. Use Responses API를 사용할지 결정합니다. 체인의 도구가 Chat Completions를 필요로 하거나 n8n 실행 로그에 chat-completions 요청이 표시되기를 원하는 경우가 아니라면 켜 두세요.
5. 트리거에 연결하기 전에 한 줄짜리 프롬프트로 워크플로를 한 번 실행하세요. 401은 키 문제입니다. 코드가 missing_v1_prefix인 404(또는 이전 실행에서 <!DOCTYPE html>로 시작하는 메시지)는 Base URL에서 /v1가 빠졌다는 뜻입니다.

n8n@2.41.4 태그의 n8n OpenAI 자격 증명 소스에서 확인했습니다(2026년 10월 1일 기준). 서드파티 설정은 변경될 수 있으므로, 여기의 필드 이름이 실제 화면과 다르면 이 문서가 아니라 해당 페이지를 기준으로 삼으세요.

클라이언트를 디버깅하기 전에 확인할 사항

한 번의 요청으로 문제가 엔드포인트, 키 또는 구성 파일 중 어디에 있는지 판단할 수 있습니다. 이 요청에서 JSON이 반환되면 동일한 base URL과 키가 n8n에서 작동합니다.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

필드에 입력할 model id

모든 텍스트 모델은 model id로 접근할 수 있습니다. 현재 목록은 GET /v1/models이며, 가격이 포함된 카탈로그는 모델 페이지에서 확인할 수 있습니다. 요금은 토큰 100만 개당 USD 기준이며 입력 / 출력 순서입니다.

Base URL이 자격 증명에 있는 이유

이전 튜토리얼에서는 모델 노드 내부에서 엔드포인트를 설정했습니다. 배포된 소스에서는 노드 버전 1.1부터 노드 내부의 Base URL 옵션이 숨겨져 있습니다. 따라서 지금 추가하는 노드에는 해당 필드가 없으며 자격 증명의 Base URL이 적용됩니다. n8n의 OpenAI Chat Model 문서와 자격 증명 페이지에는 이 필드가 설명되어 있지 않지만, 소스에는 “API의 기본 base URL 재정의”라고 설명되어 있습니다. HTTP Request 노드는 완전히 다른 방식입니다. 사용할 수는 있지만 AI Agent 노드가 대신 만들어 주는 요청을 직접 구성해야 합니다.

Responses API 켜기 또는 끄기

• 켜짐(노드 1.3의 기본값) — 요청이 /v1/responses로 전송됩니다. 이 모드에서만 노드의 Built-in Tools(Web Search, File Search, Code Interpreter)가 표시됩니다. 이는 OpenAI 호스팅 도구입니다. Kunavo를 통해 테스트한 적이 없으므로 먼저 시도해 보지 않고 이에 의존하는 워크플로를 만들지 마세요.
• 꺼짐 — 요청이 /v1/chat/completions로 전송됩니다. 가장 폭넓게 지원되는 형식이며, 다른 설정에서 도구 호출이 제대로 작동하지 않을 때 사용할 대체 설정입니다.
• AI Agent에 연결하는 도구는 함수 정의로 모델에 전송됩니다. 이번 확인에는 해당 왕복이 포함되지 않았으므로, 이에 의존하기 전에 테스트 워크플로에서 도구 호출을 한 번 실행하세요.

n8n과 OpenRouter

n8n에는 자체 OpenRouter Chat Model 노드와 전용 OpenRouter 자격 증명이 있습니다. 이 자격 증명의 API Key 필드와 Base URL은 숨겨져 있으며 https://openrouter.ai/api/v1로 고정되어 있습니다. 테스트에서는 OpenRouter 자체의 /key 경로를 호출하므로 OpenRouter 노드는 OpenRouter에만 연결됩니다. OpenRouter를 사용하려면 OpenRouter 키와 해당 노드를 사용하세요. 이 페이지의 내용은 필요하지 않습니다.

Kunavo를 포함한 다른 모든 OpenAI 호환 엔드포인트에는 위에서 설명한 대로 OpenAI Chat Model과 OpenAI 자격 증명의 Base URL을 사용합니다. 필요한 모델, 결제 방식, n8n과 다른 도구에서 잔액 하나를 함께 사용할지 등 실제 차이를 기준으로 선택하세요. 노드를 기준으로 고를 필요는 없습니다. 이 비교에서 Kunavo에 해당하는 내용은 Kunavo와 OpenRouter 비교에서 확인할 수 있습니다.

무인 워크플로의 비용 상한 유지하기

• 노드의 Max Retries 기본값은 2이고, Timeout 기본값은 60000 ms입니다. 시간 초과된 요청은 재시도되며 재시도는 새로운 청구 대상 요청입니다.
• 항목별로 실행되는 노드에는 Maximum Number of Tokens을 설정하세요. 1,000개 행을 처리하는 루프에서는 호출 1회의 비용이 그대로 곱해집니다.
• 프로덕션 워크플로마다 별도의 Kunavo 키를 사용하세요. 그러면 사용량 페이지에서 각 키의 지출 내역을 확인할 수 있고, 다른 키에 영향을 주지 않고 특정 키를 폐기할 수 있습니다.

오류 메시지 형태

• “401 Missing or invalid API key” — Base URL은 올바르고 키가 올바르지 않습니다. 2.41.4에서 재현했습니다.
• “404 <!DOCTYPE html>…”, LangChain에서는 MODEL_NOT_FOUND로 분류합니다. 오해를 부르는 메시지입니다. 모델에는 문제가 없으며 Base URL에서 /v1가 빠져 요청이 웹사이트로 전달된 것입니다. 2.41.4에서 재현했습니다.
• JSON 형식의 모델 사용 불가 메시지 — 모델 ID가 GET /v1/models와 정확히 일치하지 않습니다.