API로 챗봇 호출

스튜디오에서 만든 챗봇(시스템 프롬프트 · 지식 문서(RAG) · 도구 · 페르소나)을 내 앱이나 백엔드에서 REST API로 호출할 수 있습니다. 챗봇의 파이프라인 전체가 그대로 실행되고, 응답은 OpenAI chat.completion 형식이라 OpenAI SDK의 base_url만 바꿔서 사용할 수 있습니다.

탭	내용
시작하기	코딩 에이전트용 설정 프롬프트 카드와 「첫 호출까지 세 단계」 안내
사용량	기간별 API 호출 수 · 사용한 크레딧 · 호출당 평균, 키별 · 모델별 사용량
모델	API로 호출할 수 있는 모델 목록. 모델 종류(채팅 · 이미지 · 영상 · 오디오 · 임베딩 등)로 걸러 볼 수 있음
API 키	내 API 키 목록과 API 키 생성
요금·정책	요금 기준과 조직 보안 정책

맨 위의 이 프롬프트를 에이전트에 붙여넣으세요 카드에는 Claude Code · Codex · OpenCode 같은 코딩 에이전트에 붙여넣을 설정 프롬프트 전체가 보입니다. 복사 버튼으로 복사해 에이전트에 그대로 붙여넣으면 설정이 끝납니다. 카드 아래쪽에는 이 서비스의 Base URL이 있고, Base URL 복사 버튼으로 따로 복사할 수 있습니다. 새 키를 만들 때 나오는 창에는 그 키가 들어간 프롬프트가 함께 표시됩니다.

그 아래 첫 호출까지 세 단계는 API 키 만들기 → Base URL과 키로 호출하기 → 쓸 모델 고르기 순서로 안내합니다. 단계마다 있는 버튼을 누르면 키 만들기 창(키가 이미 있으면 API 키 탭), 개발자 문서, 모델 탭으로 이어지고, 이미 끝낸 단계에는 완료 표시가 붙습니다.

사용량

이번 달 · 지난 30일 · 지난 달 중 기간을 고르면 그 기간의 API 호출, 사용한 크레딧, 호출당 평균과 함께 키별 사용량, 모델별 사용량 표가 나옵니다. 조직에서 개인정보 마스킹을 쓰고 있다면 사용한 크레딧이 모델 사용분과 개인정보 보호 처리분으로 나뉘어 표시되고, 모델별 표에도 개인정보 보호 처리 줄이 따로 생깁니다.

요금·정책

항목	내용
요금 기준	모델별 토큰 단가. 단가는 모델 탭에서 확인합니다
조직 보안 정책	조직이 개인정보 마스킹을 쓰면 적용 중, 아니면 적용 안 함
요청당 추가 크레딧	개인정보 마스킹이 적용 중이면 모델과 관계없이 요청 1건마다 「약 N크레딧」이 더해집니다. 적용하지 않으면 없음
내역 표기	추가 크레딧은 크레딧 내역에 `mindlogic-masking`으로 기록됩니다
변경 방법	조직 관리자가 정하며, 호출 방식이나 파라미터로는 바꿀 수 없습니다

호출별 크레딧 내역

API 키 탭에서 키를 누르면 그 키의 호출 내역이 열립니다. 호출 내역의 크레딧 숫자를 누르면 입력 · 출력 · 캐시 읽기 · 캐시 쓰기 · 웹 검색 · 툴 같은 항목별 수량과 크레딧, 합계가 팝오버로 표시됩니다. 이미지 · 영상 호출이나 이전 기록처럼 항목별 내역이 없는 호출은 숫자만 보입니다.

이 화면에서 만든 키는 표시된 Base URL에서만 동작합니다. 다른 주소로 호출하면 401이 발생합니다. 인증 헤더는 Authorization: Bearer 대신 x-api-key도 쓸 수 있습니다.

활용하기

코드 예제

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

boolean

SSE 스트리밍 활성화 (기본값: false).

응답

비스트리밍 응답은 OpenAI chat.completion 형식입니다.

이 엔드포인트에서 usage는 항상 null입니다. 챗봇의 전체 파이프라인(여러 단계·여러 에이전트로 구성되는 경우가 많음)을 실행하기 때문에 호출당 prompt/completion 토큰 분할은 단일 호출 기준으로 의미 있는 값이 아닙니다. 대신 credits가 이 호출에 청구된 베이즈 크레딧(실제 과금 단위)을 나타냅니다.

챗봇이 이미지 · 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`)
콘텐츠 안전 필터	조직에 콘텐츠 안전 필터가 켜져 있고 Gateway API 적용 옵션이 활성화된 경우, 요청 메시지가 마스킹되거나 `400`으로 거부됨

과금은 동일 챗봇의 인터랙티브 채팅과 동일하며, 차이는 세션/히스토리 행을 남기지 않는다는 점뿐입니다. 사용량은 스튜디오 챗봇 상세(/dashboard/studio/[chatbot_id])에서 챗봇별로 확인할 수 있습니다.

에러

상태 코드	원인
`401`	API Key 누락 또는 유효하지 않음, 또는 키를 발급한 화면에 표시된 Base URL이 아닌 주소로 호출
`403`	조직의 Gateway API 비활성화, 또는 이 챗봇의 API 접근 스위치가 꺼짐
`404`	챗봇을 찾을 수 없음 (또는 다른 조직 소속)
`400`	지원하지 않는 챗봇 유형 (Super Agent), 또는 콘텐츠 안전 필터에 의한 거부

다음 단계

Chat Completions API — 챗봇 없이 원본 모델을 직접 호출
인증 가이드 — API Key 발급 및 사용
에러 가이드 — Gateway 공통 에러 참고

마지막 수정 날짜: Oct 13, 2026

웹사이트 임베드

고객 센터