n8n 표현식 문법으로 AI API 호출 파라미터 구성하기

실무 에피소드: 제 경험상, n8n에서 AI API를 연동할 때 가장 빈번하게遭遇하는 오류는 ExpressionError: Cannot read properties of undefined (reading 'split')입니다. 이 오류는 AI 모델 응답을 후처리할 때 자주 발생하며, 주로 표현식 문법 오류에서 비롯됩니다. 이번 튜토리얼에서는 HolySheep AI 게이트웨이를 통해 n8n에서 안정적으로 AI API를 연동하는 방법을 단계별로 설명드리겠습니다.

왜 HolySheep AI인가?

저는 실무에서 여러 AI API를 동시에 사용해야 하는 프로젝트를 진행합니다. 이때 HolySheep AI의 단일 엔드포인트가 정말 유용합니다. 1개의 API 키로 GPT-4.1, Claude Sonnet, Gemini 2.5 Flash, DeepSeek V3.2 등을 모두 호출할 수 있어서 인프라 관리가 단순해집니다. 가격도 경쟁력 있고요:

• GPT-4.1: $8/MTok
• Claude Sonnet 4.5: $15/MTok
• Gemini 2.5 Flash: $2.50/MTok
• DeepSeek V3.2: $0.42/MTok

n8n HTTP Request 노드 기본 설정

n8n에서 AI API를 호출하려면 HTTP Request 노드를 사용합니다. 가장 중요한 부분은 HolySheep AI의 엔드포인트를 정확히 설정하는 것입니다.

{
  "nodes": [
    {
      "name": "AI API Request",
      "type": "n8n-nodes-base.httpRequest",
      "position": [250, 300],
      "parameters": {
        "url": "https://api.holysheep.ai/v1/chat/completions",
        "method": "POST",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer YOUR_HOLYSHEEP_API_KEY"
            },
            {
              "name": "Content-Type",
              "value": "application/json"
            }
          ]
        },
        "sendBody": true,
        "bodyParameters": {
          "parameters": [
            {
              "name": "model",
              "value": "gpt-4.1"
            },
            {
              "name": "messages",
              "value": "={{ JSON.parse($json.input_messages) }}"
            },
            {
              "name": "temperature",
              "value": 0.7
            },
            {
              "name": "max_tokens",
              "value": 2000
            }
          ]
        }
      }
    }
  ]
}

n8n 표현식 문법 핵심 가이드

1. 기본 표현식 문법

n8n에서 표현식은 {{ }} 괄호 안에 작성합니다. 이 안에서는 JavaScript 문법을 사용할 수 있습니다.

{
  "model": "={{ $json.selected_model || 'gpt-4.1' }}",
  "messages": [
    {
      "role": "user",
      "content": "={{ $('Trigger').parameter['user_message'] }}"
    },
    {
      "role": "system", 
      "content": "={{ $json.system_prompt || '당신은 친절한 도우미입니다.' }}"
    }
  ],
  "temperature": "={{ parseFloat($json.temperature) || 0.7 }}",
  "top_p": "={{ 1 - (parseFloat($json.temperature) || 0.3) }}"
}

2. 조건부 파라미터 구성

AI API 호출 시 모델마다 다른 파라미터가 필요할 수 있습니다. 이때 삼항 연산자와 조건문을 활용합니다.

{
  "model": "={{ $json.model }}",
  "messages": "={{ $json.conversation }}",
  
  // Claude는 system 메시지가 별도 필드
  "system": "={{ $json.model.includes('claude') ? $json.system_prompt : undefined }}",
  
  // 스트리밍 설정
  "stream": "={{ $json.enable_stream === true }}",
  
  // 모델별 special tokens 설정
  "max_tokens": "={{ 
    $json.model === 'gpt-4.1' ? 4096 : 
    $json.model === 'claude-sonnet-4-5' ? 8192 : 
    $json.model === 'gemini-2.5-flash' ? 32768 : 2000 
  }}"
}

3. 배열 데이터 변환 표현식

대화 기록을 ChatML 형식으로 변환할 때 map 함수를 사용합니다. 이 부분에서 저는 처음에 많은 실수를 했었습니다.

{
  "messages": "={{ 
    $json.chat_history.map(msg => ({
      role: msg.sender === 'user' ? 'user' : 'assistant',
      content: msg.text
    })).concat([{
      role: 'user', 
      content: $('Input').parameter['new_message']
    }])
  }}"
}

실전 워크플로우: 다중 AI 모델 라우팅

저는 실무에서 하나의 워크플로우에서 여러 AI 모델을 조건부로 호출하는 경우가 많습니다. 다음은 HolySheep AI를 사용한 모델 라우팅 예제입니다.

{
  "nodes": [
    {
      "name": "Model Router",
      "type": "n8n-nodes-base.switch",
      "parameters": {
        "dataType": "string",
        "value1": "={{ $json.intent }}",
        "rules": {
          "rules": [
            { "value2": "code", "output": 0 },
            { "value2": "creative", "output": 1 },
            { "value2": "fast", "output": 2 }
          ]
        }
      }
    },
    {
      "name": "GPT-4.1 (Reasoning)",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://api.holysheep.ai/v1/chat/completions",
        "method": "POST",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            { "name": "Authorization", "value": "Bearer YOUR_HOLYSHEEP_API_KEY" },
            { "name": "Content-Type", "value": "application/json" }
          ]
        },
        "sendBody": true,
        "bodyParameters": {
          "parameters": [
            { "name": "model", "value": "gpt-4.1" },
            { "name": "messages", "value": "={{ $json.messages }}" },
            { "name": "temperature", "value": 0.3 },
            { "name": "max_tokens", "value": 4096 },
            { "name": "reasoning_effort", "value": "high" }
          ]
        }
      }
    },
    {
      "name": "DeepSeek V3.2 (Fast)",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://api.holysheep.ai/v1/chat/completions",
        "method": "POST",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            { "name": "Authorization", "value": "Bearer YOUR_HOLYSHEEP_API_KEY" },
            { "name": "Content-Type", "value": "application/json" }
          ]
        },
        "sendBody": true,
        "bodyParameters": {
          "parameters": [
            { "name": "model", "value": "deepseek-v3.2" },
            { "name": "messages", "value": "={{ $json.messages }}" },
            { "name": "temperature", "value": 0.7 },
            { "name": "max_tokens", "value": 2000 }
          ]
        }
      }
    }
  ]
}

자주 발생하는 오류와 해결책

오류 1: ExpressionError - Cannot read properties of undefined

원인: 표현식에서 참조하는 데이터가 존재하지 않을 때 발생합니다.

{
  // ❌ 잘못된 방법 - $json.messages가 undefined일 경우 에러
  "messages": "={{ $json.messages.map(m => m.content) }}"
  
  // ✅ 해결 방법 - 옵셔널 체이닝 사용
  "messages": "={{ ($json.messages || []).map(m => m.content) }}"
  
  // 또는 기본값 제공
  "messages": "={{ $json.messages ?? [{ role: 'user', content: '' }] }}"
}

오류 2: 401 Unauthorized - Invalid API Key

원인: HolySheep AI API 키가 유효하지 않거나 Authorization 헤더 형식 오류입니다.

{
  // ❌ 잘못된 형식 - 따옴표 불필요
  "name": "Authorization",
  "value": "Bearer 'YOUR_HOLYSHEEP_API_KEY'"
  
  // ✅ 올바른 형식
  "name": "Authorization", 
  "value": "={{ 'Bearer ' + $env.HOLYSHEEP_API_KEY }}"
  
  // 환경 변수 설정 (n8n Credentials에서)
  // env.HOLYSHEEP_API_KEY = "hsa_xxxxx..."
}

추가 확인사항:

• API 키가 HolySheep AI 대시보드에서 활성 상태인지 확인
• 크레딧 잔액이 충분한지 확인 (0 크레딧 시 401 반환)
• API 키 앞에 hsa_ 접두사가 있는지 확인

오류 3: 422 Unprocessable Entity - Invalid Request Body

원인: messages 배열 형식이 ChatML 스펙과 맞지 않거나, 지원하지 않는 파라미터 사용입니다.

{
  // ❌ 잘못된 messages 구조
  "messages": "={{ { text: $json.user_input, from: 'user' } }}"
  
  // ✅ 올바른 ChatML 구조  
  "messages": "={{ [{ role: 'user', content: $json.user_input }] }}"
  
  // ❌ 지원하지 않는 파라미터
  "unsupported_param": "={{ $json.value }}"
  
  // ✅ 지원 파라미터만 사용
  "model": "gpt-4.1",
  "messages": "={{ $json.messages }}",
  "temperature": 0.7,
  "max_tokens": 2000
}

오류 4: TimeoutError - Request Timeout

원인: AI API 응답 지연이 n8n 기본 타임아웃을 초과할 때 발생합니다.

{
  "timeout": 120000,  // 2분으로 증가
  
  // 또는 재시도 로직 추가
  "options": {
    "retry": {
      "maxRetries": 2,
      "retryWait": 3000,
      "retryMaxWait": 30000
    }
  }
}

저의 경험담: Gemini 2.5 Flash는 평균 응답 속도가 약 800ms 정도로 빠르지만, DeepSeek V3.2는 복잡한 쿼리 시 3-5초까지 걸릴 수 있습니다. 따라서 모델별 타임아웃을 다르게 설정하는 것이 효율적입니다.

오류 5: CORS 에러 (클라이언트 사이드)

원인: 브라우저에서 직접 HolySheep AI API를 호출할 때 발생합니다.

{
  // ❌ 브라우저에서 직접 호출 (CORS 오류 발생)
  fetch('https://api.holysheep.ai/v1/chat/completions', {...})
  
  // ✅ 해결 방법: 항상 서버 사이드(n8n 워크플로우)에서 호출
  // n8n HTTP Request 노드는 서버 투 서버 통신이므로 CORS 문제 없음
  
  // 또는 HolySheep AI 대시보드에서 CORS 설정 확인
  // Allowed Origins에 자신의 도메인 추가
}

성능 최적화 팁

저는 HolySheep AI를 통해 월 100만 토큰 이상을 처리하는데, 다음 팁들이 비용 최적화에 도움되었습니다:

• 모델 선택: 단순 QA는 Gemini 2.5 Flash ($2.50/MTok), 복잡한 추론은 GPT-4.1 ($8/MTok)
• max_tokens 제한: 필요 이상으로 크게 설정하지 않기 (응답 길이 제어)
• 배치 처리: 여러 요청을 묶어서 처리하면 API 호출 횟수 감소
• 캐싱: 동일한 프롬프트에 대해 캐시 활용

결론

n8n 표현식 문법은 처음에는 복잡해 보이지만, 기본 패턴인 {{ }} 문법과 JavaScript 연산자를 이해하면 AI API 파라미터를 유연하게 구성할 수 있습니다. HolySheep AI의 단일 엔드포인트(https://api.holysheep.ai/v1)를 사용하면 여러 AI 모델을 쉽게 전환하면서도 일관된 워크플로우를 유지할 수 있습니다.

저의 경우, 이전에는 모델마다 다른 엔드포인트를 관리해야 했지만, HolySheep AI 도입 후엔 API 키 하나와 엔드포인트 하나로 모든 것을 처리하게 되었습니다. 특히 개발 단계에서 여러 모델을 빠르게 전환하며 테스트할 수 있는 유연성이 큰 도움이 되었습니다.

👉 HolySheep AI 가입하고 무료 크레딧 받기