API로 챗봇 호출
스튜디오에서 만든 챗봇(시스템 프롬프트 · 지식 문서(RAG) · 도구 · 페르소나)을 내 앱이나 백엔드에서 REST API로 호출할 수 있습니다. 챗봇의 파이프라인 전체가 그대로 실행되고, 응답은 OpenAI
chat.completion 형식이라 OpenAI SDK의 base_url만 바꿔서 사용할 수 있습니다.시작하기
이 기능을 쓰려면 세 가지가 모두 필요합니다.
- 조직에서 Gateway API가 활성화돼 있음 — 기본값은 활성화입니다. 조직 정책상 꺼져 있다면 관리자 화면에는 켜는 설정이 없으므로 마인드로직 담당 매니저에게 활성화를 요청해야 합니다. (활성화 전 호출 시
403) - 챗봇에 API 접근을 명시적으로 허용 — 스튜디오 챗봇 상세 페이지 헤더의 공유 버튼을 눌러 팝오버를 열고, API 탭의 "API로 이 챗봇 호출하기" 스위치를 켭니다. 챗봇마다 개별 opt-in이며 기본값은 꺼짐입니다.
- Gateway API Key 발급 — 인증 가이드를 따라 발급받습니다.
챗봇 id는 스튜디오 대시보드 URL에서 확인합니다 (
/dashboard/studio/[chatbot_id]).활용하기
코드 예제
Python (OpenAI SDK)
curl
엔드포인트
POST
/v1/gateway/chatbots/{chatbot_id}/chat/completions/지정한 챗봇으로 대화 완성을 생성합니다. 챗봇에 설정된 모델 · 시스템 프롬프트 · 문서 · 도구가 자동으로 적용됩니다. 일반 RAG 챗봇과 워크플로우 챗봇을 지원합니다. Super Agent 챗봇은 별도 실행 환경을 사용하므로 이 엔드포인트에서
400으로 거부됩니다.파라미터
messages
대화 기록 (array
required
role + content). 엔드포인트는 상태를 저장하지 않으므로(stateless), 멀티턴 대화를 이어가려면 매 호출마다 이전 턴을 모두 함께 보내야 합니다 (OpenAI Chat Completions와 동일).model 파라미터는 없습니다. 챗봇에 설정된 모델이 사용됩니다. system 메시지는 무시됩니다 — 시스템 프롬프트는 챗봇이 소유합니다.stream
SSE 스트리밍 활성화 (기본값: boolean
false).응답
비스트리밍 응답은 OpenAI
chat.completion 형식입니다.이 엔드포인트에서
usage는 항상 null입니다. 챗봇의 전체 파이프라인(여러 단계·여러 에이전트로 구성되는 경우가 많음)을 실행하기 때문에 호출당 prompt/completion 토큰 분할은 단일 호출 기준으로 의미 있는 값이 아닙니다. 대신 credits가 이 호출에 청구된 FactChat 크레딧(실제 과금 단위)을 나타냅니다.챗봇이 이미지 · PPT · 코드 실행 결과 등 파일을 생성했다면
files 배열에 서명된 다운로드 URL이 담기고, 같은 링크가 content의 markdown에도 함께 추가되어 콘텐츠만 읽는 클라이언트도 링크를 놓치지 않습니다. 파일을 만들지 않는 챗봇은 files가 빈 배열입니다.스트리밍 응답
stream: true인 경우 OpenAI chat.completion.chunk 델타를 SSE로 전송한 뒤 다음 순서로 종료됩니다.- 정상 종료: 파일이 생성된 경우 markdown 링크가
content델타로 추가됨 →finish_reason: "stop"청크 →choices가 빈 배열이고usage: null·credits·files를 담은 트레일러 청크 →data: [DONE] - 오류 종료 (크레딧 소진, 업스트림 LLM 오류 등): credits 트레일러 청크가 먼저 전송된 뒤 (오케스트레이터가 오류 직전까지 이미 과금했을 수 있음) →
data: {"error": {...}}이벤트 →data: [DONE]
비스트리밍 경로에서는 텍스트나 파일이 조금이라도 생성됐으면 partial completion으로 정상 응답(
200)을 반환합니다. 텍스트 · 파일이 모두 비어 있고 업스트림에서 실패한 경우에만 502를 반환합니다.동작 방식
API 호출 1건 = API Key 소유 멤버가 해당 챗봇과 대화하는 것과 동일합니다. 단, 세션/히스토리는 저장하지 않습니다.
| 항목 | 동작 |
|---|---|
| 접근 권한 · 크레딧 | 인터랙티브 채팅과 동일하게 챗봇 접근 권한 · 모델 유효성 · 크레딧을 검증·차감 |
| 세션 / 히스토리 | 저장하지 않음 (stateless) |
| 대화 분석 · 키워드 | 제외 (세션 기반 분석에서 자동 제외 — API 트래픽은 사람의 대화 신호가 아님) |
| 사용량 (크레딧 · 토큰) | usage 기록 (usage_type=apikey + api_key_id + chatbot_id) |
| 대화 내용 (질의 · 응답) | audit_log에 기록 (api_source="chatbot_api") |
| 콘텐츠 안전 필터 | 조직에 콘텐츠 안전 필터가 켜져 있고 Gateway API 적용 옵션이 활성화된 경우, 요청 메시지가 마스킹되거나 400으로 거부됨 |
과금은 동일 챗봇의 인터랙티브 채팅과 동일하며, 차이는 세션/히스토리 행을 남기지 않는다는 점뿐입니다. 사용량은 스튜디오 챗봇 상세(
/dashboard/studio/[chatbot_id])에서 챗봇별로 확인할 수 있습니다.에러
| 상태 코드 | 원인 |
|---|---|
401 | API Key 누락 또는 유효하지 않음 |
403 | 조직의 Gateway API 비활성화, 또는 이 챗봇의 API 접근 스위치가 꺼짐 |
404 | 챗봇을 찾을 수 없음 (또는 다른 조직 소속) |
400 | 지원하지 않는 챗봇 유형 (Super Agent), 또는 콘텐츠 안전 필터에 의한 거부 |
다음 단계
- Chat Completions API — 챗봇 없이 원본 모델을 직접 호출
- 인증 가이드 — API Key 발급 및 사용
- 에러 가이드 — Gateway 공통 에러 참고
마지막 수정 날짜: Aug 07, 2026