n8n

n8n은 워크플로 자동화 도구입니다. SpicyAPI는 하나의 API와 하나의 선불 잔액으로 이미지, 영상, 오디오, 채팅 모델을 n8n에 제공합니다. 연결 방법은 세 가지이며, 한 워크플로 안에서 섞어 쓸 수 있습니다.

세 방법 모두 같은 계정, 키, 모델, 가격을 씁니다. 미디어 생성에서는 노드와 HTTP Request 템플릿이 제출 전에 요청 가격을 확인합니다. 이미 접수된 같은 미디어 생성 요청을 원래 Idempotency-Key로 다시 보내면 기존 작업을 반환합니다.

이미지 워크플로의 출발점이 필요하다면 n8n NSFW 이미지 워크플로 가이드를 보세요. 모델 선택, 참조 이미지 편집, 첫 인물 이미지와 비용 예제를 다룹니다. 아래 단계로 자신의 n8n 인스턴스에 연결할 수 있습니다.

시작하기 전에

• API 키. 콘솔에서 만드세요. 키는 sk-spicy-로 시작합니다. 아직 계정이 없다면 계정 설정을 보세요.
• 잔액. 첫 생성 전에 콘솔 Billing에서 충전하세요. n8n 워크플로, Studio, API는 같은 계정 잔액을 씁니다. 정산 방식은 과금을 보세요.
• 자동화마다 키 하나. 워크플로는 사람이 클릭하는 것보다 훨씬 자주 실행될 수 있습니다. n8n 전용 키를 따로 만들고 일일 또는 월 지출 한도를 설정해, 반복문의 실수가 상한을 넘지 않게 하세요. 인증을 보세요.
• n8n이 api.spicyapi.ai에 접속할 수 있어야 합니다. 호출은 브라우저가 아니라 n8n 서버가 보냅니다.

방법 1: SpicyAPI 커뮤니티 노드

이 노드는 github.com/spicyapi-ai/n8n-nodes-spicyapi에서 오픈 소스(MIT)로 공개되어 있고 npm에 @spicyapi/n8n-nodes-spicyapi로 배포됩니다. 런타임 의존성이 없고 api.spicyapi.ai하고만 통신합니다.

이름이 비슷한 다른 npm 패키지도 있지만 관련 없는 서비스의 것입니다. 이 노드는 @spicyapi/n8n-nodes-spicyapi라는 이름의 패키지이며, 자격 증명 이름은 SpicyAPI (spicyapi.ai) API입니다.

설치

cd ~/.n8n/nodes
npm install @spicyapi/n8n-nodes-spicyapi

작업

이미지, 영상, 오디오 생성하기

세 가지 Generate 작업은 같은 입력칸을 공유합니다.

1. Model. 선택한 리소스의 모델이 시작 가격과 함께 표시되는 목록에서 고르거나, 모델 ID를 직접 입력하세요. 모든 모델과 파라미터는 spicyapi.ai/models에 있습니다.
2. Prompt. 모델의 주된 텍스트 입력입니다. 음성 모델에서는 읽을 텍스트입니다. 업스케일러처럼 프롬프트가 없는 모델에서는 비워 두세요.
3. Media Inputs. 모델이 읽는 이미지, 영상, 오디오입니다. 필드를 고른 다음(목록에 선택한 모델의 파일 입력이 표시됩니다) 이전 노드의 바이너리 필드나 URL을 사용하세요. 바이너리 파일은 SpicyAPI에 자동으로 업로드됩니다. 참조 이미지처럼 목록형 필드를 채우려면 같은 필드에 입력을 여러 개 추가하세요.
4. Model Parameters. 선택한 모델의 스키마로 생성된 양식입니다. 화면 비율, 해상도, 길이, 시드 등이 있습니다. 비워 둔 필드는 전송되지 않으므로 모델이 자체 기본값을 씁니다.
5. Additional Parameters (JSON). 그 밖의 입력 필드를 JSON 객체로 지정합니다. 위의 필드보다 우선합니다.

출력에는 작업 레코드(taskId, state, cost, settled, output)가 들어 있습니다. Download Output이 켜져 있으면(기본값) 파일도 data, data_1 등의 바이너리 데이터로 첨부됩니다. output.assets[].url의 링크는 약 20분 뒤에 만료되며, 바이너리 사본은 만료되지 않습니다.

n8n이 바이너리 데이터를 디스크에 저장하지 않으면 큰 영상은 메모리에 보관됩니다. 셀프 호스팅 n8n에서 영상을 다룰 때는 N8N_DEFAULT_BINARY_DATA_MODE=filesystem을 설정하세요.

비용 관리와 재시도

• 모든 항목은 먼저 가격이 산정됩니다. 노드가 견적을 요청합니다. 견적이 Max Cost per Item (USD)(기본값 $2)을 넘으면 아무것도 생성되기 전에 오류와 함께 멈추며, 요금은 부과되지 않습니다. 제한을 없애려면 0으로 설정하세요.
• 작업은 견적받은 가격으로 생성됩니다. 견적과 제출 사이에 가격이 바뀌면 노드가 다시 견적을 받고, 한도를 다시 확인한 뒤 다시 제출합니다.
• 재시도해도 두 번 결제되지 않습니다. 비용 한도와 재시도를 보세요.

오래 걸리는 작업

선택지와 각각을 쓸 때는 오래 걸리는 영상 작업을 보세요.

방법 2: HTTP Request 템플릿

가져와서 쓸 수 있는 워크플로 두 개는 n8n 기본 노드만 쓰므로, 커뮤니티 노드 없이 셀프 호스팅 n8n과 n8n Cloud에서 모두 실행됩니다. 노드 저장소의 examples 폴더에 있습니다.

이미지 템플릿의 구조

어떤 미디어 모델에서든 같은 단계가 통하므로, 이 패턴을 내 워크플로에 복사해 쓸 수 있습니다.

요청과 응답의 형식은 작업, 견적과 호환성, 미디어 입력과 출력에 있습니다. 시작 이미지처럼 모델이 읽는 파일은 공개 URL이나 업로드한 spicy:// 파일이면 됩니다.

방법 3: AI Agent와 다른 AI 노드의 채팅 모델

SpicyAPI의 채팅 엔드포인트는 OpenAI 호환이므로 n8n의 기본 OpenAI 노드가 이를 쓸 수 있습니다. 이를 위해 커뮤니티 노드가 필요하지 않으며 n8n Cloud에서도 작동합니다.

https://api.spicyapi.ai/v1

알아 둘 점은 다음과 같습니다.

• 모델 목록에는 이미지와 영상 모델도 포함됩니다. Base URL을 직접 지정하면 n8n은 /v1/models가 반환하는 모든 것을 표시하고, SpicyAPI의 목록에는 모든 모델이 들어 있습니다. /chat으로 끝나는 모델을 고르거나 expression 모드에서 ID를 직접 입력하세요. 이미지와 영상 모델은 채팅 모델이 아니므로 에이전트에서 실패합니다.
• Use Responses API. 최근 버전의 OpenAI Chat Model 노드는 /v1/chat/completions 대신 /v1/responses로 요청을 보낼 수 있습니다. SpicyAPI는 /v1/responses를 지원하지만 previous_response_id는 지원하지 않습니다. Responses API를 켠 상태에서 에이전트 요청이 실패하면 노드에서 Use Responses API를 끄세요.
• 샘플링 설정. 추론 모델의 temperature처럼 모델이 선언하지 않은 옵션을 설정하면 SpicyAPI는 실패시키지 않고 무시하며, 무시한 이름을 X-Spicy-Ignored-Params 응답 헤더에 나열합니다. 모델의 범위를 벗어난 값은 가장 가까운 허용 값으로 바뀌고 X-Spicy-Adjusted-Params에 나열됩니다. 그 밖의 선언되지 않은 필드는 여전히 400을 반환합니다.
• 도구와 JSON 출력은 모델에 따라 다릅니다. /v1/models에서 해당 모델의 supported_parameters를 확인하세요.
• 추론 모델은 추론 토큰을 max_tokens에 포함합니다. 20처럼 아주 작은 값에서는 추론 모델이 예산 전부를 생각에 쓰고 텍스트를 반환하지 않을 수 있습니다(upstream_failed: "the output budget was spent on reasoning"). max_tokens를 올리거나 reasoning_effort를 낮추세요. reasoning_effort의 값은 모델마다 다릅니다.
• 스트리밍과 비용. 채팅은 호출이 끝난 뒤 토큰 수만큼 과금됩니다. 자세한 내용은 텍스트와 스트리밍 페이지에, 요청 예시는 채팅 레시피에 있습니다.

비용 한도와 재시도

지출 제한

• 콘솔에서 일일 또는 월 지출 한도를 건 n8n 전용 키를 쓰고, 워크플로에 모델 몇 개만 필요하다면 모델 허용 목록도 설정하세요. 한도에 도달하면 호출은 40202로 실패하고 그 호출에는 요금이 부과되지 않습니다.
• 미디어 모델은 먼저 견적을 받으세요. 노드는 이를 대신 해 주고, 템플릿은 Get Quote와 If 노드로 처리합니다. 견적은 참조 이미지당 요금 같은 추가 항목까지 포함한 그 요청의 정확한 가격이므로, 견적을 기준으로 한 가격 확인은 믿을 수 있지만 카탈로그 표를 기준으로 한 확인은 그렇지 않습니다.
• 일반적인 실패와 만료된 작업은 보류 금액을 전액 해제합니다. 일부 콘텐츠 거부는 해당 모델 페이지에 과금한다고 명시된 경우에만 청구됩니다. 최종 청구액은 settled와 cost로 확인하세요. 과금을 참고하세요.

재시도해도 두 번 결제되지 않는 이유

작업을 생성하는 모든 호출에는 Idempotency-Key가 붙습니다. 같은 요청에 같은 키가 다시 도착하면 SpicyAPI는 두 번째 작업을 만들지 않고 이미 만든 작업을 반환하므로 두 번째 보류도, 결제도 일어나지 않습니다. n8n에서는 내가 아무것도 하지 않아도 요청이 두 번 전송될 수 있어서 이것이 중요합니다. 노드의 Retry On Fail이나, 첫 요청이 실제로는 처리되었는데 발생한 타임아웃이 그런 경우입니다.

• 커뮤니티 노드는 실행, 노드, 항목, 입력으로 키를 만듭니다. 노드 재시도는 같은 키를 재사용합니다. 새 실행, 바뀐 입력, 반복문의 다른 회차는 새로운 작업이므로 새 키를 받습니다.
• 템플릿은 실행 ID와 항목 인덱스로 키를 만듭니다. 예: n8n-<execution id>-<item index>. 이 패턴을 반복문에 복사해 쓴다면 키에 반복 횟수를 추가하세요. 그러지 않으면 모든 회차가 첫 회차의 작업을 반환합니다.
• $now처럼 시도할 때마다 바뀌는 임의의 값은 쓰지 마세요. 모든 재시도가 새 작업처럼 보이게 됩니다.

자세한 내용은 멱등성에 있습니다.

오래 걸리는 영상 작업

이미지와 오디오 모델은 보통 요청 하나 안에서 끝납니다. 영상은 몇 분이 걸릴 수 있습니다. 이를 다루는 방법은 세 가지이며, 가장 단순한 것부터 n8n에 가장 부담이 적은 것 순서입니다.

노드가 기다리기를 멈추더라도 작업은 SpicyAPI에서 계속 진행되며, 성공하면 요금이 부과됩니다. 나중에 Task > Get으로 가져오세요. 다시 제출하지 마세요. 콘솔의 Logs에서도 찾을 수 있습니다.

결과는 일정 기간만 보관되고 내려받기 링크는 약 20분 동안만 유효합니다. 더 오래 필요하면 워크플로 안에서 클라우드 스토리지 등에 파일을 저장하세요. 보관 기간을 보세요.

문제 해결

SpicyAPI가 반환하는 오류는 끝에 request_id나 작업 ID가 붙습니다. 지원팀에 이 값을 알려 주면 해당 요청을 정확히 찾을 수 있습니다. 오류 코드는 오류에 설명되어 있고, 더 폭넓은 점검 목록은 문제 해결에 있습니다.

모델 사용에는 SpicyAPI 약관과 내가 실행하는 n8n 에디션의 약관이 적용됩니다.