allanbunch/node-red-openai-api

이 프로젝트는 OpenAI API 및 OpenAI 호환 API를 Node-RED의 워크플로우 네이티브 빌딩 블록(building blocks)으로 가져옵니다.

이 노드는 사람들이 검사, 라우팅, 테스트 및 운영할 수 있는 런타임(runtime)에 현대적인 AI 기능들을 제공합니다: 요청 및 응답 워크플로우(workflows), 도구(tools), 대화(conversations), 스트리밍(streaming), 실시간 상호작용(realtime interactions), 웹훅(webhooks), 그리고 실제 시스템에서 중요한 관련 API 제품군들이 포함됩니다.

이로 인해 이 저장소는 Node-RED를 넘어선 관련성을 가집니다. 이는 현대적인 AI 기능이 단일 벤더의 인터페이스에 갇히거나 하나의 목적만을 가진 추상화 뒤에 숨겨지는 대신, 어떻게 개방형 워크플로우 환경 내에서 존재할 수 있는지에 대한 실질적인 구현 사례입니다.

이 패키지는 현재 openai Node SDK ^6.37.0 버전을 대상으로 합니다.

현대적인 AI 작업은 더 이상 단순히 "프롬프트를 보내고 문자열을 돌려받는 것"에 그치지 않습니다.

실제 시스템은 이제 다음을 포함합니다:

• 도구 사용 (tool use)
• 다단계 워크플로우 (multi-step workflows)
• 구조화된 페이로드 (structured payloads)
• 스트리밍 응답 (streaming responses)
• 실시간 세션 (realtime sessions)
• 웹훅 검증 (webhook verification)
• 제공자 호환성 및 인증 라우팅 (provider compatibility and auth routing)

Node-RED는 이미 오케스트레이션(orchestration), 자동화(automation), 이벤트 처리(event handling), 통합(integration) 및 운영 명확성(operational clarity) 측면에서 뛰어납니다. 이 프로젝트는 이러한 강점들을 OpenAI API 인터페이스와 연결하여, 팀들이 가시성이 확보되고 조합 가능한(composable) 환경에서 AI 워크플로우를 구축할 수 있도록 합니다.

이 저장소의 노드 모델은 의도적으로 단순하게 설계되었습니다:

• 하나의 OpenAI API 노드가 런타임 메서드 호출을 처리합니다.
• 하나의 Service Host 설정 노드가 API 기본 URL(base URL), 인증(auth), 조직(organization) 설정을 처리합니다.
• 선택된 메서드에 따라 어떤 OpenAI API 컨텍스트가 호출될지 결정됩니다.
• 요청 데이터는 기본적으로 설정 가능한 메시지 속성인 msg.payload를 통해 전달됩니다.
• 메서드별 세부 사항은 에디터 도움말, 예제 플로우(example flows), 그리고 기반이 되는 SDK 규약(contract)에 명시되어 있습니다.

실제로 이는 하나의 노드가 플로우 자체를 특수 목적 노드들의 미로로 만들지 않고도 광범위한 API 인터페이스를 커버할 수 있음을 의미합니다.

이 노드를 사용하여 직접적인 생성 (generation), 구조화된 응답 (structured Responses) API 작업, 채팅 스타일의 상호작용 (chat-style interactions), 모더레이션 (moderation), 임베딩 (embeddings), 이미지 작업, 오디오 작업 및 기타 요청/응답 (request/response) 패턴을 수행할 수 있습니다.

여기에는 플로우의 필요에 따라 내장된 음성 또는 저장된 사용자 정의 음성 ID (custom voice id)를 사용하는 음성 작업이 포함됩니다.

Node-RED 내부에서 OpenAI 비디오 작업을 수행할 때 이 노드를 사용하십시오. 여기에는 생성을 위한 현재의 Sora 비디오 메서드, 리믹스 (remix), 편집 (edit), 확장 (extend), 캐릭터 생성 (character creation) 및 다운로드 가능한 비디오 에셋 (video assets)이 포함됩니다. 이를 통해 비디오 기능이 나머지 AI 시스템과 동일하게 가시적이고 라우팅 가능한 워크플로우 (workflow) 환경 내에서 작동할 수 있습니다.

더 큰 제어 루프 (control loops) 및 운영 워크플로우 (operational workflows)의 일부로 응답 (Responses) 도구, 대화 (conversations), 실행 (runs), 메시지 (messages), 벡터 스토어 (vector stores), 파일 (files), 스킬 (skills) 및 관련 리소스를 사용하십시오. 게시된 에이전트 빌더 (Agent Builder) 워크플로우를 Node-RED 플로우 내에 깔끔하게 노출해야 하는 경우 ChatKit 세션 (sessions) 및 스레드 (threads)를 사용하십시오.

플로우가 단발성 요청 처리 (one-shot request handling) 이상의 기능이 필요한 경우, 스트리밍된 응답 (streamed Responses) 출력, 실시간 클라이언트 비밀 생성 (Realtime client-secret creation), SIP 호출 작업 (SIP call operations) 및 지속적인 응답 웹소켓 (Responses websocket) 연결을 사용하십시오.

상위 플랫폼 이벤트에 반응하는 Node-RED 플로우에서 웹훅 서명 검증 (webhook signature verification) 및 페이로드 언래핑 (payload unwrapping)을 사용하십시오.

사용자 정의 기본 URL (custom base URLs), 사용자 정의 인증 헤더 이름 (custom auth header names), 쿼리 문자열 인증 라우팅 (query-string auth routing) 및 타입 지정된 설정 값 (typed configuration values)을 통해 호환 가능한 API 제공업체를 대상으로 하려면 Service Host 설정을 사용하십시오.

• Node.js
  >=18.0.0

• Node-RED
  >=3.0.0

@inductiv/node-red-openai-api

cd $HOME/.node-red
npm i @inductiv/node-red-openai-api

• 플로우에 OpenAI API 노드를 드롭합니다.
• Service Host 설정 노드를 생성하거나 선택합니다.
• API Base를 제공업체의 엔드포인트로 설정합니다. 기본 OpenAI 값은 https://api.openai.com/v1 입니다.
• API Key를 다음 중 하나를 사용하여 설정합니다: 저장된 자격 증명 값을 위한 cred, 또는 런타임 참조를 위한 env, msg, flow, global.
• OpenAI API 노드에서 create model response와 같은 메서드를 선택합니다.
• msg.payload를 통해 요청 페이로드 (request payload)를 전송합니다.

, 또는 플로우 (flow)에서 다른 메시지 형태 (message shape)를 사용하는 경우 노드의 입력 속성 (input property)을 변경하십시오.

create model response를 위한 msg.payload 예시:

{
"model": "gpt-5.4-mini",
"input": "Write a one-line status summary."
...

노드는 출력을 다시 msg.payload에 작성합니다.

Create Conversation Item은 이제 상위 OpenAI Conversations 계약 (contract)을 따릅니다.

msg.payload.items를 배열 (array)로 사용하십시오.

단일 msg.payload.item 객체를 전송하는 이전 플로우는 더 이상 지원되는 계약 (contract)과 일치하지 않으므로, 이번 릴리스 (release)로 이동하기 전에 반드시 업데이트해야 합니다.

이 노드의 형태를 빠르게 이해하고 싶다면, 다음 예시 플로우 (example flows)들이 가장 좋은 시작점입니다:

examples/chat.json: 방향을 잡기 위한 간단한 API 호출 (API-call) 플로우입니다.
examples/admin.json: 프로젝트 목록, 감사 로그 (audit-log) 검색, 속도 제한 (rate-limit) 검사 및 속도 제한 업데이트를 포함하여, 조직 및 프로젝트 제어를 위한 관리자 (Admin) 인터페이스를 보여줍니다.
examples/chatkit/sessions-and-threads.json: 게시된 Agent Builder 워크플로우 (workflow)를 위한 ChatKit 세션 (session)을 생성 및 취소하는 방법과, 그 결과로 생성된 스레드 (thread) 및 스레드 아이템 (thread items)을 검사하는 방법을 보여줍니다.
examples/conversations.json: items 배열과 보존된 assistant-message phase 값을 사용하는 Conversations 생성 아이템 계약 (contract)을 보여줍니다.
examples/responses/phase.json: 최신 페이로드 (payload) 기능을 사용하는 깔끔한 Responses 예시입니다.
examples/responses/tool-search.json: 도구 (tool)가 활성화된 Responses가 실제적인 플로우에서 작동하는 방식을 보여줍니다.
examples/responses/web-search.json: include, top_logprobs, prompt_cache_retention을 포함한 현재의 웹 검색 (web-search) 요청 형태를 보여줍니다.
examples/responses/computer-use.json: 컴퓨터 사용 (computer-use) 스타일의 워크플로우를 위한 요청 및 후속 계약 (contract)을 보여줍니다.
examples/responses/websocket.json: 하나의 노드 인스턴스 (node instance)에서 명시적인 웹소켓 (websocket) 생명주기 (lifecycle) 처리를 보여줍니다.
examples/videos.json: 생성, 캐릭터 생성, 편집, 확장, 리믹스 (remix), 에셋 다운로드 (asset download)를 포함한 현재의 비디오 플로우 인터페이스를 보여줍니다.
examples/vector-store-search.json

ComparisonFilter와 in, nin 연산자를 사용한 직접적인 벡터 스토어 (vector-store) 검색을 보여줍니다.
examples/realtime/client-secrets.json

브라우저 또는 모바일 핸드오프 (handoff)를 위한 Realtime 클라이언트 비밀키 (client-secret) 계약을 보여줍니다.

이 저장소는 현재 다음을 포함합니다:

• Admin API 키 라우팅, 조직 감사 로그 (organization audit logs), 조직 프로젝트 제어, 프로젝트 속도 제한 (rate-limit) 작업, 그리고 에디터 내의 일급 (first-class) Admin 메서드 제품군을 포함한 Admin API 지원

• 세션 생성 및 취소, 그리고 게시된 워크플로우에 대한 스레드 (thread) 및 스레드 항목 (thread-item) 검사를 포함한 ChatKit / Agent Builder 지원

• create-item 요청을 위한 상위 items 배열 계약 및 assistant-message의 phase 값인 commentary와 final_answer를 포함한 대화 (Conversations) 지원

• gpt-5.4-mini, gpt-5.4-nano와 같은 현재 SDK 타입 모델 ID 및 gpt-5.4-mini-2026-03-17과 같은 날짜 지정 변형을 포함한 Responses API 지원. 또한 phase, input_file.detail, prompt_cache_key, prompt_cache_retention 값인 in_memory, include 값인 web_search_call.results, top_logprobs, tool_search, defer_loading을 통한 지연된 MCP 로딩, GA computer-use 페이로드 (payloads), 파싱 및 스트림 헬퍼 (helpers), 취소, 압축 (compaction), 입력 토큰 계산, 그리고 웹소켓 (websocket) 모드 포함. Responses 요청 형태의 일치 (parity) 작업은 런타임에서 의도적으로 얇게 유지됩니다: 생성 (create), 스트림 (stream), 압축 (compact) 호출은 직접적인 SDK 패스스루 (pass-through)이며, 이 저장소는 변환 로직을 추가하는 대신 집중적인 문서, 예제 및 회귀 테스트 (regression tests)를 통해 로컬에서 해당 계약을 증명합니다.

• 직접적인 벡터 스토어 (vector-store) 검색, 벡터 스토어 파일 속성 업데이트, 파싱된 파일 콘텐츠 검색, 그리고 in 및 nin과 같은 ComparisonFilter 연산자를 사용하는 파일 속성 필터를 포함한 Vector Stores 지원

• 클라이언트 비밀키 (client-secret) 생성, SIP 호출 작업, 그리고 gpt-realtime-1.5 및 gpt-audio-1.5와 같은 현재 SDK 타입 모델 ID를 포함한 Realtime API 지원

• 내장된 음성 및 저장된 커스텀 음성 ID를 통한 오디오 음성 (Audio speech) 지원

• 생성, 리믹스 (remix), 편집 (edit), 확장 (extend), 캐릭터 생성 및 다운로드 가능한 에셋을 포함한 비디오 (Videos) / Sora 지원

• 컨테이너 (Containers), 컨테이너 파일 (Container Files), 평가 (Evals), 스킬 (Skills) 및 웹훅 (Webhooks) 지원

• Service Host 설정 노드 (config node)를 통한 OpenAI 호환 인증 라우팅 (auth routing)

정확한 메서드 페이로드 (method payloads) 및 공식 API 문서 링크는 에디터 내 노드 도움말을 참조하세요.

메서드 선택기 (method picker)는 다음과 같은 광범위한 OpenAI API 제품군을 다룹니다:

• Admin (관리)
• Assistants (어시스턴트)
• Audio (오디오)
• Batch (배치)
• Chat Completions (채팅 완성)
• ChatKit (챗킷)
• Container Files (컨테이너 파일)
• Containers (컨테이너)
• Conversations (대화)
• Embeddings (임베딩)
• Evals (평가)
• Files (파일)
• Fine-tuning (파인튜닝)
• Images (이미지)
• Messages (메시지)
• Models (모델)
• Moderations (모더레이션)
• Realtime (리얼타임)
• Responses (응답)
• Runs (실행)
• Skills (스킬)
• Threads (스레드)
• Uploads (업로드)
• Vector Store File Batches (벡터 스토어 파일 배치)
• Vector Store Files (벡터 스토어 파일)
• Vector Stores (벡터 스토어)
• Videos (비디오)
• Webhooks (웹훅)

Graders (채점자)는 공식 SDK가 모델링하는 방식과 동일하게, testing_criteria를 통한 Evals 페이로드를 통해 지원됩니다.

가져오기 준비가 된 예제 플로우 (example flows)는 examples/ 디렉토리에 있습니다:

examples/admin.json

examples/assistants.json

examples/audio.json

examples/chat.json

examples/chatkit/sessions-and-threads.json

examples/conversations.json

examples/embeddings.json

examples/files.json

examples/fine-tuning.json

examples/images.json

examples/messages.json

examples/models.json

examples/moderations.json

examples/realtime/client-secrets.json

examples/responses/computer-use.json

examples/responses/mcp.json

examples/responses/phase.json

examples/responses/tool-search.json

examples/responses/web-search.json

examples/responses/websocket.json

examples/videos.json

examples/vector-store-search.json

examples/runs.json

examples/threads.json

Service Host 설정 노드는 제공자별 런타임 경계 (runtime boundary)를 처리합니다.

API Key는 cred, env, msg, flow, global을 지원합니다.

Admin API Key는 관리자 인증이 필요한 OpenAI 경로를 위해 cred, env, msg, flow, global을 지원합니다.
API Base

OpenAI 또는 호환 가능한 제공업체를 가리킬 수 있습니다.
Auth Header (인증 헤더)

기본값은 Authorization 이지만, 일반적인 API 키 경로에서 제공업체별 인증 관례에 따라 변경할 수 있습니다. 일반적인 API 키 경로의 경우 인증은 헤더(header) 또는 쿼리 문자열(query-string) 파라미터로 전송될 수 있습니다.
Organization ID (조직 ID)

선택 사항이며 다른 서비스 필드와 마찬가지로 타입이 지정된 값(typed values)을 지원합니다.

이 부분은 하나의 런타임 모델이 OpenAI와 호환되는 API 인터페이스 모두에서 깔끔하게 작동할 수 있도록 해줍니다.

이 저장소는 런타임(runtime), 에디터(editor), 예제(examples) 및 생성된 아티팩트(artifacts)를 이해하기 쉽게 구조화되어 있습니다:

node.js

Node-RED 런타임 진입점 및 Service Host (서비스 호스트) 설정 노드(config-node) 로직입니다.
src/

메서드 구현, 에디터 템플릿 및 도움말 콘텐츠를 위한 소스 모듈입니다.
src/lib.js

번들링된 런타임 메서드 인터페이스를 위한 소스 진입점입니다.
lib.js

src/lib.js로부터 빌드된 생성된 런타임 번들입니다.
src/node.html

패밀리별 조각(fragments)을 포함하는 소스 에디터 템플릿입니다.
node.html

src/node.html로부터 빌드된 생성된 에디터 자산(asset)입니다.
examples/

즉시 가져오기(Import) 가능한 Node-RED 플로우(flows)입니다.
test/

에디터 동작, 인증 라우팅(auth routing), 메서드 매핑(method mapping) 및 웹소켓(websocket) 라이프사이클 동작에 대한 Node 테스트 커버리지입니다.

npm install
npm run build
npm test

생성된 파일은 프로젝트의 일부입니다:

node.html은 src/node.html로부터 빌드됩니다.
lib.js는 src/lib.js로부터 빌드됩니다.

소스 템플릿이나 런타임 소스 파일을 변경하는 경우, 검토 또는 릴리스 전에 다시 빌드하십시오.

이 프로젝트는 실제 운영 중인 OpenAI 플랫폼을 대상으로 유지 관리됩니다. 이는 특히 새로운 기능과 새로운 모델을 적절히 테스트해야 할 때, API 사용, 테스트, 동등성 작업(parity work) 및 릴리스 검증을 위한 실제 지속적인 비용이 발생함을 의미합니다.

이 패키지가 귀하 또는 귀하의 팀에 유용하다면, GitHub Sponsors를 통한 후원이 해당 작업이 계속 진행될 수 있도록 큰 도움이 됩니다.

기여(Contributions)는 언제나 환영합니다. 변경 사항을 명확하고 의도적이며 검증된 상태로 유지해 주세요.

다음 내용을 포함해 주세요:

• 명확한 범위(scope) 및 근거(rationale)
• 동작 변경에 대한 테스트
• 새로 추가하거나 수정하는 각 테스트 파일 상단에 평이한 언어로 작성된 짧은 주석 블록
• 사용자에게 노출되는 동작이 변경될 경우 문서(doc) 업데이트