Sidetalk사용자 가이드
사이드톡 홈페이지 ↗대시보드 열기
가이드 홈사용자 가이드

학습용 데이터 답변 생성 API

4 분 읽기가이드 기준일: 2026. 10. 14.노션 원문 보기 ↗

목적

저장된 학습용 질문·답변 데이터를 기준으로 답변을 조회하고, AI를 한 번 호출하여 답변을 정리한 뒤 반환합니다. stream 값에 따라 일반 JSON 또는 SSE 스트림으로 받을 수 있습니다.

URL

Plain Text
https://api.sidetalk.ai/v1/knowledge/completions

HTTP 메서드

Plain Text
POST

요청 본문

파라미터타입필수설명
questionString조건부knowledgeId가 없을 때 저장된 질문과 정확히 일치하는 데이터를 찾는 데 사용합니다.
knowledgeIdString조건부학습용 데이터 1건을 식별하는 ID입니다. 조회 API 응답의 data[].knowledgeId 값을 그대로 전달하는 것을 권장합니다.
streamBoolean아니요false(기본값)이면 일반 JSON, true이면 SSE 스트림으로 반환합니다.
sessionIdString아니요채팅 로그에 사용할 세션 ID입니다.
knowledgeId 또는 question 중 하나는 전달해야 합니다. 두 값을 모두 전달하면 knowledgeId를 우선 사용합니다.

요청 예시

knowledgeId로 조회하는 요청

Bash
curl -X POST "https://api.sidetalk.ai/v1/knowledge/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "knowledgeId": "456",
    "stream": false
  }'

기존 세션으로 요청

Bash
curl -X POST "https://api.sidetalk.ai/v1/knowledge/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "knowledgeId": "456",
    "sessionId": "943f15db-3984-4f21-ad64-f0115839c3a6",
    "stream": false
  }'

성공 응답(200 OK)

JSON
{
  "success": true,
  "knowledgeId": "456",
  "sessionId": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "message": {
    "content": "배송은 결제 후 2~3일 이내에 진행됩니다."
  },
  "recommended_questions": [
    {
      "knowledgeId": "3356",
      "question": "배송 조회는 어떻게 하나요?",
      "type": "chat_data"
    }
  ],
  "meta": {
    "chat_log_uuid": "uuid",
    "knowledgeId": "456",
    "sessionId": "943f15db-3984-4f21-ad64-f0115839c3a6",
    "latency_ms": 850,
    "used_credit": 1,
    "tokens": {
      "input_tokens": 100,
      "output_tokens": 30,
      "total_tokens": 130,
      "token_cost": 0
    }
  }
}

오류 응답

상태 코드설명
400JSON 형식 또는 필수 식별 정보가 잘못되었습니다.
402API 사용 크레딧이 부족합니다.
403API 키 인증에 실패했습니다.
404조건에 맞는 학습용 답변을 찾을 수 없습니다.
500답변 생성 중 서버 오류가 발생했습니다.
JSON
{
  "success": false,
  "error": "Answer not found"
}
참고: 이 API는 지정된 학습용 데이터의 답변을 조회한 뒤 AI 포매팅을 한 번 적용하는 API입니다.

스트림 요청(stream: true)

stream을 true로 보내면 대화형 API와 같은 SSE 형식으로 응답합니다. metadata 이벤트 다음에 choices[].delta.content 형식의 데이터 청크가 오고, 마지막에 finish_reason: "stop" 청크와 [DONE]이 전송됩니다. knowledgeId는 메타데이터와 모든 데이터 청크에 포함됩니다.
Bash
curl -N -X POST "https://api.sidetalk.ai/v1/knowledge/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "knowledgeId": "456",
    "stream": true,
    "sessionId": "api-session-1"
  }'
응답 예시는 다음과 같습니다.
JSON
event: metadata
data: {"knowledgeId":"456","sessionId":"api-session-1","chat_log_uuid":"uuid"}

data: {"id":"chatcmpl-uuid","object":"chat.completion.chunk","created":1731042399,"knowledgeId":"456","choices":[{"index":0,"delta":{"content":"배송은 "},"finish_reason":null}]}

data: {"id":"chatcmpl-uuid","object":"chat.completion.chunk","created":1731042399,"knowledgeId":"456","choices":[{"index":0,"delta":{"content":"결제 후 2~3일 이내에 진행됩니다."},"finish_reason":null}]}

data: {"id":"chatcmpl-uuid","object":"chat.completion.chunk","created":1731042399,"knowledgeId":"456","choices":[{"index":0,"delta":{},"finish_reason":null}],"sidetalk_event":{"type":"recommendedQuestions","data":{"items":[{"knowledgeId":"3356","question":"배송 조회는 어떻게 하나요?","type":"chat_data"}]}}}

data: {"id":"chatcmpl-uuid","object":"chat.completion.chunk","created":1731042399,"knowledgeId":"456","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"meta":{"chat_log_uuid":"uuid","knowledgeId":"456","sessionId":"api-session-1","latency_ms":850,"used_credit":1,"tokens":{"input_tokens":100,"output_tokens":30,"total_tokens":130,"token_cost":0}}}

data: [DONE]
일반 JSON 응답에는 recommended_questions 배열이 포함됩니다. 직접 연결된 추천질문이 없으면 유사도 기반 추천질문이 최대 3개 반환될 수 있습니다.
추천 질문의 식별자도 knowledgeId이며, type은 추천 데이터의 종류입니다.
스트림에서는 답변 청크와 같은 data 형식으로 다음 이벤트가 추가됩니다.
JSON
data: {"id":"chatcmpl-uuid","object":"chat.completion.chunk","created":1731042399,"knowledgeId":"456","choices":[{"index":0,"delta":{},"finish_reason":null}],"sidetalk_event":{"type":"recommendedQuestions","data":{"items":[{"knowledgeId":"3356","question":"배송 조회는 어떻게 하나요?","type":"chat_data"}]}}}

data: {"id":"chatcmpl-uuid","object":"chat.completion.chunk","created":1731042399,"knowledgeId":"456","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
knowledgeId 없이 question만 전달하는 경우, 저장된 학습용 질문과 정확히 일치하는 데이터를 조회합니다. 답변 조회 후 추천질문이 없으면 유사도 기반 추천질문이 자동으로 조회될 수 있습니다.