Prediction API로 연동하기

Prediction API로 연동하기

Flowise에서 만든 플로우를 다른 앱에 붙일 때 가장 먼저 쓰는 엔드포인트가 Prediction API예요. 채팅플로우나 어시스턴트에 메시지를 보내고 응답을 받는 핵심 경로로, 스트리밍, 대화 메모리, 파일 처리, 런타임 설정 오버라이드까지 다 지원해요.

출처: https://docs.flowiseai.com/api-reference/prediction

기본 URL과 인증

로컬 Flowise 인스턴스를 기준으로 기본 URL은 http://localhost:3000(설치한 Flowise 인스턴스 URL)이에요. 엔드포인트는 POST /api/v1/prediction/:id 형태이고, :id 자리에 호출할 플로우의 ID를 넣어요.

플로우 설정에 따라 API 키가 필요할 수 있어요. 인증 방식은 bearer 토큰(Authorization: Bearer <key>)을 쓰고, 보안을 위해 설정에서 키를 발급받아 사용하세요.

요청 파라미터

파라미터 타입 설명
question string 플로우에 보낼 메시지/질문
form object Agentflow V2에서 question 대신 쓸 수 있는 폼 객체
streaming boolean 실시간 스트리밍 응답 여부(기본 false)
overrideConfig object 플로우 설정을 런타임에 오버라이드·변수 전달
history array 이전 대화 메시지 문맥
uploads array 이미지·오디오 등 업로드 파일
humanInput object 중단 지점에서 사람의 피드백을 받고 재개

question이나 form 중 하나는 필수예요. streaming은 기본 false고, 실시간 응답이 필요하면 true로 켜면 돼요.

응답 필드

정상적인 요청(200)의 응답 JSON에는 이런 값들이 들어와요.

  • text: AI가 생성한 응답 문자열.
  • json: 구조화된 출력을 쓴 경우 JSON 결과(없으면 null).
  • question: 보낸 원래 질문.
  • chatId, chatMessageId: 채팅 세션과 메시지의 고유 ID.
  • sessionId: 대화 연속성용 세션 식별자.
  • memoryType: 대화 문맥에 쓰인 메모리 타입.
  • sourceDocuments: RAG를 켰다면 벡터 스토어에서 검색된 문서 배열.
  • usedTools: 응답 생성 중 호출된 도구 배열.

오류 상황은 상태 코드로 구분돼요. 400(잘못된 입력), 401(API 키 누락/무효), 404(플로우 없음), 413(페이로드 초과), 422(검증 실패), 500(플로우 설정·실행 오류) 흐름으로 처리하면 돼요.

세션과 메모리

sessionId를 지정하면 여러 API 호출 사이에 대화 상태가 유지돼요. 세션마다 각자의 문맥과 메모리를 갖게 되니까, 같은 사용자 대화는 같은 sessionId로 이어 보내는 게 좋아요.

더 알아보기

  • 플로우를 실제로 만드는 법은 «채팅플로우 만들기»를 보세요.
  • overrideConfig의 변수나 humanInput 재개 흐름은 Flowise의 Using Flowise 가이드를 참고하세요.