시작하기 전에 필요한 항목
n8n 인스턴스(클라우드 또는 자체 호스팅)와 이 서비스의 API 키가 필요합니다. 아직 키가 없는 경우 API 키 페이지에서 Google 또는 이메일과 비밀번호로 가입하는 방법을 안내합니다. 새 사용자는 해당 페이지에서 한 번의 클릭으로 7일 동안 유효하고 카드가 필요 없는 $0.50의 무료 체험 크레딧을 받을 수 있습니다.
n8n에 세 가지 값이 들어갑니다:
- Base URL:
https://api.onekeyllmapi.com/v1 - API 키:
Authorization: Bearer <key>로 전송되며, n8n이 이를 처리합니다. - 모델 ID:
uncensored
이 서비스는 OpenAI 요청 형식을 따르는 호스팅된 텍스트 전용 LLM API로, /v1/chat/completions, /v1/responses 및 /v1/models을 사용합니다. 이는 어떤 모델 벤더의 공식 API도 아니므로, n8n이 OpenAI의 채팅 엔드포인트로 보내는 텍스트 요청이라면 모두 여기서 작동합니다.
단계 1: 자격 증명 만들기
n8n에서 Credentials를 열고, Create credential을 선택한 후 OpenAI API를 검색합니다. 다음과 같이 채워 넣으세요:
- 키를 API Key 필드에 붙여넣으세요.
- Organization ID를 비워 두세요.
- 기본 Base URL을
https://api.onekeyllmapi.com/v1로 바꿉니다. 끝에/v1을 유지하고/chat/completions을 추가하지 마세요. - 저장하세요. n8n은 저장할 때 작은 테스트 호출을 실행합니다. 실패하는 경우 아래 문제 해결 섹션으로 이동하세요.
환경마다 자격 증명을 하나씩 유지하세요. 스테이징과 프로덕션 n8n을 각각 실행한다면 각기 다른 키를 부여하여 사용량을 별도로 확인하고 한쪽만 취소해도 다른 쪽에 영향을 주지 않도록 하세요.
단계 2: 간단한 채팅 워크플로우 만들기
연결을 증명하는 가장 작은 것부터 시작하세요: 수동 트리거와 하나의 모델 호출입니다.
- Manual Trigger 노드를 추가하세요.
- OpenAI 노드(또는 n8n 버전에 따라 Basic LLM Chain 내의 OpenAI Chat Model 하위 노드)를 추가하고 1단계의 자격 증명을 선택하세요.
- 모델의 경우 ID를 직접 입력할 수 있는 방법을 찾아보세요. 최신 n8n 버전에는 목록 옆에 By ID 모드가 있습니다. 거기에
uncensored를 입력하세요. 목록이 비어 있거나 OpenAI 이름만 표시될 수 있습니다. n8n이 자체적으로 필터링하기 때문입니다. - 이 지원 티켓을 두 문장으로 요약하세요와 같은 프롬프트를 추가하고 노드를 실행하세요.
n8n 버전이 목록에서 선택하도록 강요하는 경우 다음 섹션의 HTTP Request 접근 방식을 사용하세요. 전체 요청을 제어할 수 있으므로 항상 작동합니다.
HTTP Request 노드를 사용하여 API 호출하기
HTTP Request 노드는 n8n에서 이 API를 호출하는 가장 예측 가능한 방법이며, seed, stop, top_p 및 tools을 포함하여 API가 허용하는 모든 매개변수를 노출합니다. 다음과 같이 구성하세요:
- 메서드:
POST - URL:
https://api.onekeyllmapi.com/v1/chat/completions - 인증: Generic Credential Type와 Header Auth, 이름
Authorization, 값Bearer YOUR_KEY - 본문 보내기: 켜짐, 콘텐츠 유형 JSON
본문 (이전 노드에서 데이터를 삽입하려면 필드를 Expression로 전환하세요):
{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Summarize this support ticket in two sentences."}
],
"temperature": 0.4
}
응답 텍스트는 choices[0].message.content에 있습니다. 다음 노드에서는 {{ $json.choices[0].message.content }}로 참조할 수 있습니다.
n8n 외부에서 동일한 요청을 테스트하려면 터미널에서 다음을 실행하세요:
curl https://api.onekeyllmapi.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say hello in five words."}]}'
curl이 작동하고 n8n이 작동하지 않으면 문제는 키나 잔액이 아닌 노드 설정에 있습니다.
출력을 구문 분석하는 워크플로우용 JSON 모드
모델이 데이터를 친절한 문장으로 감싸면 워크플로우가 중단됩니다. JSON 모드는 API가 유효한 JSON 객체를 반환하도록 요청하며, 이를 Set 또는 IF 노드에 직접 전달할 수 있습니다. 본문에 response_format을 추가하세요:
{
"model": "uncensored",
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Reply only with a JSON object with keys sentiment and summary."},
{"role": "user", "content": "The delivery was late but support fixed it fast."}
]
}
이것을 안정적으로 만드는 두 가지 습관이 있습니다. 먼저 프롬프트에서 JSON이라는 단어를 사용하고 키 이름을 명시하세요. JSON 모드는 스키마가 아닌 구문을 보장하기 때문입니다. 둘째, 응답은 여전히 message.content에 문자열로 전달되므로 필드를 읽기 전에 코드 노드나 JSON.parse() 표현식을 추가하세요. OpenAI 노드에서는 이 설정이 노드 옵션 아래의 응답 형식 옵션으로 나타납니다.
429 및 기타 오류 처리
n8n은 항목을 병렬로 실행하므로 50개 행의 배치로 인해 제한에 빠르게 도달할 수 있습니다. 전체 키는 동시 8개 요청 및 분당 300개 요청을 허용하며, 체험 키는 동시 2개 및 분당 60개 요청을 허용합니다. 제한을 초과하면 API는 코드 rate_limited(분당 요청 수 초과) 또는 concurrency(동시 요청 수 초과)와 함께 HTTP 429를 반환합니다. 일시적인 과부하 시에는 Retry-After: 5 헤더와 함께 429를 받습니다.
n8n의 실용적인 설정:
- 노드를 열고, Settings로 이동한 후, Retry On Fail을 활성화하고, Max Tries을 3 또는 4로, Wait Between Tries을 5000 ms로 설정하세요.
- 모델 호출 전에 Loop Over Items 노드(배치 크기 4~6)를 배치하여 병렬 요청이 8개를 넘지 않도록 하세요.
- 노드 Settings에서, On Error은 오류 출력으로 계속하도록 설정할 수 있으므로 하나의 잘못된 행이 실행을 중단하지 않습니다.
두 가지 유형의 제한에 대해 더 자세히 알아보려면 API 문서를 읽으세요. 기타 오류는 단순합니다. 401은 키가 잘못되었거나 헤더에 Bearer 단어가 누락되었음을 의미하며, 404는 일반적으로 Base URL에 오타가 있거나 불필요한 경로 세그먼트가 있음을 의미합니다.
문제 해결 체크리스트
대부분의 실패는 짧은 원인 목록에서 비롯됩니다. 서비스를 의심하기 전에 위에서 아래로 순서대로 확인하세요.
| 증상 | 잠재적 원인 | 해결 방법 |
|---|---|---|
| 저장 또는 실행 시 401 | 잘못된 키, 또는 헤더에 Bearer 누락 | 키를 다시 붙여넣으세요. Header Auth의 값은 Bearer 로 시작해야 합니다. |
| 404 | Base URL에 오타가 있거나 불필요한 경로가 있음 | 자격 증명에 정확히 https://api.onekeyllmapi.com/v1를 사용하세요. |
| 모델을 찾을 수 없음 | 모델 ID가 uncensored로 입력되지 않았습니다. | ID별로 전환하거나 HTTP 요청 노드를 사용하세요. |
| 동시성 관련 429 | 8개를 초과하는 동시 실행 (시험용 키는 2개) | 항목 반복으로 배치 처리하고 재시도를 추가하세요. |
| 하류에서 JSON 파싱 오류 발생 | 응답이 문자열이거나 프롬프트에서 키를 지정하지 않았습니다. | JSON.parse()로 파싱하고 시스템 프롬프트에 키들을 설명하세요. |
지원팀에 문의할 때 실패한 호출의 X-Request-Id 응답 헤더를 포함하세요. n8n에서는 HTTP 요청 노드 옵션에서 응답 헤더 및 상태 포함을 활성화하여 헤더를 확인할 수 있습니다.
비용을 많이 들이지 않고 테스트하기
빌드하는 동안 시험용 크레딧을 사용하세요. 동시 요청 2개, 분당 요청 60개의 제한으로 시험용 키는 배치 처리에는 느리지만 자격 증명, 프롬프트 및 파싱 로직을 확인하기에는 충분합니다. 워크플로우를 스케줄로 전환할 때 전체 키로 전환하세요.
비용과 합리적인 워크플로우 설계
가격은 선불 크레딧에서 차감되는 종량제입니다: 입력 토큰 1M당 $0.15, 출력 토큰 1M당 $0.50입니다. 하루 1,000개의 이메일을 분류하는 워크플로우에서 각 이메일이 600개의 입력 토큰과 100개의 출력 토큰을 사용한다면, 입력 토큰 0.6M($0.09)과 출력 토큰 0.1M($0.05)이 사용되어 하루 약 $0.14가 발생합니다. 실패하거나 거부된 요청에는 요금이 부과되지 않으므로 오류 시 재시도로 요금이 두 배로 증가하지 않습니다. 자세한 내용은 가격 책정 페이지에서 확인하세요.
프롬프트를 짧게 유지하고 모델이 필요한 필드만 전송하며, 답변이 짧을 것으로 예상되면 max_tokens을 설정하세요. 로컬 머신에서 모델을 실행하는 경우 동일한 클라이언트 설정을 사용하는 OpenAI 스타일 API를 통한 로컬 LLM 사용 기사를 참조하세요.
