Activepieces 플로우에 OpenAI 호환 AI 프로바이더를 연결하기.

빠른 답: 관리자 AI 설정에 프로바이더 항목 하나.

Activepieces 관리자 콘솔에서 AI setup 페이지를 열고 OpenAI Compatible 타입의 프로바이더를 추가하세요. 폼은 Display Name, API Key, Base URL, API Key Header, 선택적 기본 헤더, 그리고 각 항목이 Model ID, Model Name, Model Type을 갖는 모델 목록을 받습니다. APIsRouter의 값은 다음과 같습니다: Base URL은 https://api.apisrouter.com/v1(코드베이스가 자체 내장 호환 프로바이더에 사용하는 것과 같은 형태)이고, API Key Header는 Authorization이며, 키 필드에는 게이트웨이 키를 넣습니다. 알아둘 만한 구현 세부사항 하나: Activepieces는 입력한 그대로 그 헤더에 키를 보내며 Bearer 프리픽스를 자동으로 붙이지 않으므로, 정석대로 하려면 "Bearer sk-..."로 입력하세요. APIsRouter는 Authorization 헤더에 프리픽스 없는 키도 받아들이므로 어느 쪽이든 동작합니다. 그런 다음 플로우가 볼 수 있게 하고 싶은 모델들을 Model ID가 카탈로그와 정확히 일치하도록 추가하세요.

Admin Console -> AI setup -> Add AI Provider
  -> OpenAI Compatible

Display Name:   APIsRouter
Base URL:       https://api.apisrouter.com/v1
API Key Header: Authorization
API Key:        Bearer sk-YOUR-APISROUTER-KEY

Models (Add Model):
  Model ID: claude-haiku-4-5-20251001  Type: TEXT
  Model ID: deepseek-v4-flash          Type: TEXT
  Model ID: claude-sonnet-4-6          Type: TEXT

Activepieces가 커스텀 프로바이더를 사용하는 방식.

Activepieces(GitHub에서 약 2.3만 스타)는 선두적인 오픈소스 노코드 자동화 플랫폼입니다: 트리거와 piece로 구성되는 플로우를 Zapier와 비슷한 형태로 제공하되 셀프 호스팅이 가능하며, MIT 라이선스의 piece 프레임워크와 방대한 커뮤니티 카탈로그를 갖추고 있습니다. 이 플랫폼의 AI 기능(텍스트 생성 스텝, 에이전트, AI 유틸리티 piece)은 모델을 플랫폼에 설정된 AI 프로바이더로부터 해석하며, 이 때문에 프로바이더 항목 하나가 곧 모든 플로우에 대한 라우팅 결정이 됩니다. 내부적으로 OpenAI Compatible 프로바이더는 여러분의 Base URL을 대상으로 표준 클라이언트를 구성하고, 선택한 헤더 이름으로 키를 붙이며, 여기에 프로젝트와 플로우를 식별하는 실행별 메타데이터 헤더를 추가합니다. 등록한 Model ID는 chat-completions 요청의 model 문자열로 그대로 전달됩니다. 이 프로바이더 타입에는 모델 자동 탐색이 없습니다: 플로우는 목록에 추가한 모델만 정확히 선택할 수 있으므로, 선택지가 산만해지지 않고 의도한 대로 유지됩니다. 프로바이더 설정은 플랫폼 레벨입니다. 관리자가 한 번 정의하면 인스턴스의 모든 프로젝트와 플로우가 등록된 모델 중에서 선택합니다. 이 중앙집중화가 곧 거버넌스의 이점입니다: 어떤 모델이 존재할지 결정하는 곳도 하나, 모든 AI 스텝을 계량하는 키도 하나, 그리고 각 요청에 담긴 플로우별 메타데이터 덕분에 로그를 볼 때 사용량 귀속도 가능합니다.

전체 설정과 저장 시점의 주의점.

이 폼은 연결을 검증하지 않고 저장됩니다; 프로바이더 구현은 OpenAI Compatible 타입에 대해 연결 확인을 명시적으로 건너뜁니다. 저장 시점에 엔드포인트를 프로빙하지 않는다는 점에서 편리하지만, 잘못된 Base URL이나 잘못된 형식의 키가 나중에, 즉 AI 스텝을 건드리는 첫 플로우 실행에서 실패한다는 뜻이기도 합니다. 프로덕션 플로우에 연결하기 전에 한 번 직접 엔드포인트를 검증하고, 첫 실행을 설정 과정의 일부로 취급하세요. Model Type은 어떤 piece가 그 항목을 쓸 수 있는지에 영향을 줍니다: 텍스트 스텝은 TEXT 모델을 원합니다. id는 카탈로그가 표기한 그대로 정확히 등록하세요; Model Name은 표시용 라벨이므로 읽기 쉬운 아무 이름이나 써도 됩니다. 같은 기반 모델을 팀별로 다른 가격/성능 티어로 두고 싶다면 Model ID별로 한 번씩 등록하세요; 표시 이름이 선택지에서 이들을 구분해 줍니다.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50

curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001",
       "messages":[{"role":"user","content":"ping"}]}'

자동화 스텝을 위한 모델 선택.

프로바이더가 플랫폼 전역이기 때문에 모델 거버넌스는 화면 하나로 끝납니다: 승인한 id를 추가하고, 일주일치 키별 사용량을 지켜보고, 아무도 써서는 안 될 것을 정리하세요. 플로우 빌더는 여러분이 엄선한 목록 안에서 자유를 유지합니다.

• 자동화 AI는 대량의 짧은 프롬프트 작업입니다: 티켓 분류, 필드 추출, 메시지 초안 작성, 웹훅 페이로드 요약. claude-haiku-4-5-20251001, gpt-5.4-mini, deepseek-v4-flash가 대부분의 스텝을 볼륨 가격으로 처리합니다.
• 판단이 필요한 스텝에는 더 강한 id를 아껴두세요. 고객 대면 답변 초안을 쓰거나 라우팅 결정을 내리는 플로우는 플로우 빌더에서 스텝별로 선택하는 claude-sonnet-4-6을 받을 자격이 있습니다.
• MiniMax-M2.7과 DeepSeek 계열은 하루에 수천 번 실행이 정상인 대량 변환 플로우(피드, 스크래핑 정리, 보강)에서 매우 좋은 가격을 냅니다.
• 플로우는 무인으로 실행되므로, 비용은 스케줄에 실행당 토큰 수를 곱한 값입니다. 사용량 로그가 실행당 숫자를 알려주며, 스케줄은 여러분의 몫입니다.
• 모델은 의도적으로 적게 등록하세요. 선택지는 추가한 것만 정확히 보여주며, 엄선된 목록은 백 명의 플로우 빌더가 제각각 다른 선택을 하지 않도록 막아줍니다.

사용한 만큼 지불 · 공식 요금보다 저렴

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Activepieces 특유의 실패 패턴.

저장은 조용히, 첫 실행은 요란하게. OpenAI Compatible 프로바이더가 연결 검증을 건너뛰기 때문에, 모든 배선 실수(잘못된 Base URL, 빠진 /v1, 잘못된 키, 잘못된 헤더 이름)는 폼 오류가 아니라 플로우 실행에서 실패한 AI 스텝으로 드러납니다. 프로바이더 변경 직후 AI 스텝이 실패한다면 플로우보다 먼저 프로바이더 항목을 의심하세요. Bearer 프리픽스 문제. 키는 선택한 헤더 아래로 그대로 전송됩니다. Bearer 프리픽스가 문자 그대로 필요한 엔드포인트라면 키 필드에 직접 입력해야 합니다; APIsRouter는 두 형식 모두 받아들이지만, 언젠가 이 프로바이더를 다른 곳으로 재지정한다면 플랫폼이 여러분 대신 프리픽스를 붙여주지 않는다는 점을 기억하세요. Model ID는 정확해야 합니다. 오타가 있는 등록된 id는 폼을 통과하지만(라벨은 자유 텍스트입니다) 실행 시점에 model-not-found로 실패합니다; 게이트웨이의 /v1/models 출력이 정확한 표기의 기준입니다. 자동 탐색이 없는 것은 버그가 아니라 기능입니다. 플로우의 선택지에 모델이 빠져 있다면 프로바이더에 등록되지 않은 것입니다; 플로우 빌더를 뒤지지 말고 관리자 콘솔에 추가하세요. 그리고 piece 레벨 연결은 머릿속에서 따로 구분해 두세요: OpenAI piece 같은 개별 piece는 연결마다 자체 자격 증명을 가질 수 있는 반면, 여기서 설명한 프로바이더 항목은 플랫폼의 범용 AI 기능을 구동합니다. 플로우가 자체 연결을 가진 벤더 전용 piece를 쓴다면 그 트래픽은 게이트웨이 항목을 거치지 않습니다.

어떤 사람들이 게이트웨이를 통해 Activepieces를 쓰는가.

• 수십 개 플로우 전반의 AI를 표준화하려는 셀프 호스팅 팀 — 프로바이더 항목 하나와 키 하나가 흩어진 piece별 자격 증명을 대체합니다.
• 모델 거버넌스를 원하는 플랫폼 관리자: 엄선된 모델 목록, 키별 사용량, 그리고 플로우를 건드리지 않고 백엔드 엔드포인트를 교체할 수 있는 능력.
• 한 인스턴스에서 여러 클라이언트의 자동화를 운영하며, 같은 카탈로그에서 별도 키로 클라이언트별 AI 사용량을 계량하는 에이전시.
• 볼륨 스텝과 판단 스텝이 섞인 플로우를 만드는 빌더 — 하나의 엔드포인트로 스텝별로 빠른 id와 프론티어 id를 짝지을 수 있습니다.
• 특정 벤더의 결제 수단에 접근할 수 없는 개발자. 카드 없이 충전만으로 사용할 수 있어 프로바이더별 가입 의존성이 사라집니다.

엔드포인트 검증 및 첫 AI 스텝 디버깅.

프로바이더를 저장하기 전에 위의 curl 두 개를 실행하세요; 키, Base URL, 모델 id가 함께 맞는지 증명하는데, 이는 정확히 폼이 대신 확인해주지 않는 부분입니다. 설정 후 플로우의 AI 스텝이 실패하면 스텝 오류를 읽으세요. 인증 실패는 키 필드나 헤더 이름이 잘못됐다는 뜻입니다(또는 Bearer 프리픽스가 필요한 엔드포인트에서 빠졌다는 뜻). model-not-found 오류는 등록된 id가 카탈로그와 일치하지 않는다는 뜻입니다. 연결 오류는 보통 Base URL에서 /v1이 빠졌다는 뜻입니다. 스텝이 선택할 모델을 하나도 못 찾는다면 프로바이더는 저장됐지만 해당 모델 타입에 대한 모델 목록이 비어 있다는 뜻입니다. 플로우가 실행되기 시작하면 APIsRouter 콘솔에서 요청별 모델, 토큰 수, 지출을 볼 수 있습니다. 예약 자동화는 조용히 누적되므로, 키별 사용량 뷰는 청구서가 나오기 전에 어떤 플로우가 실제로 토큰값을 하는지 플랫폼 관리자가 확인하는 방법입니다.

자주 묻는 질문