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

대화형 파일 첨부 API

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

관련 문서

대화형 답변 생성 API (V2)

목적

이 API는 문서 파일을 업로드하고, 업로드된 파일을 특정 대화 세션에 연결합니다.
업로드된 파일은 문서 파싱 후 텍스트로 추출되며, 같은 session_id로 채팅을 요청하면 AI가 필요에 따라 해당 파일 내용을 참고할 수 있습니다.
session_id가 없으면 서버에서 새 세션을 발급하고, 파일은 새로 발급된 세션에 연결됩니다.

1. 세션 파일 업로드 API


URL



HTTP 메서드

Plain Text
POST

헤더

헤더값설명
AuthorizationBearer <api_key>Sidetalk 대시보드에서 제공된 API 키를 사용하세요.
multipart/form-data 요청에서는 브라우저나 HTTP 클라이언트가 Content-Type과 boundary를 자동으로 설정하도록 두는 것을 권장합니다.

본문

파라미터타입필수설명
fileFile예업로드할 문서 파일입니다.
session_idString아니요파일을 연결할 세션 ID입니다. 없으면 서버에서 새로 발급합니다.
sessionIdString아니요session_id의 alias입니다.

지원 파일 형식

확장자설명
pdfPDF 문서
xlsxExcel 문서
xlsExcel 문서
csvCSV 파일
txt텍스트 파일
docxWord 문서
docWord 문서
pptxPowerPoint 문서
pptPowerPoint 문서

파일 크기 제한

파일 형식제한
txt, csv3MB 이하
pdf, xlsx, xls, docx, doc, pptx, ppt20MB 이하

session_id 정책

상황동작
session_id 없음서버에서 새 session_id를 생성하고 파일을 해당 세션에 연결합니다.
session_id 있음 + 유효함해당 세션에 파일을 연결합니다.
session_id 있음 + 형식이 잘못됨오류를 반환합니다.
session_id 있음 + 존재하지 않음오류를 반환합니다.
권장 방식은 다음과 같습니다.
  1. 채팅 API 응답에서 받은 session_id가 있으면 파일 업로드 시 함께 전달합니다.
  2. session_id 없이 파일을 먼저 업로드할 수도 있습니다.
  3. 이 경우 파일 업로드 응답에서 받은 session_id를 이후 채팅 요청에 사용합니다.

요청 예시


session_id 없이 파일 업로드

JSON
curl -X POST https://api.sidetalk.ai/v1/chat/files \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "file=@관리자매뉴얼.pdf"

기존 세션에 파일 업로드

JSON
curl -X POST https://api.sidetalk.ai/v1/chat/files \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "session_id=943f15db-3984-4f21-ad64-f0115839c3a6" \
  -F "file=@관리자매뉴얼.pdf"

성공 응답 예시

JSON
{
  "success": true,
  "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "result": {
    "file_id": "file_9e17c4df-5b4a-48c8-8e8f-3de7c6e9c5a1",
    "id": 15,
    "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
    "file_name": "관리자매뉴얼.pdf",
    "content_chars": 9527,
    "summary_chars": 247
  }
}

응답 필드 설명

필드타입설명
successBoolean요청 성공 여부입니다.
session_idString파일이 연결된 세션 ID입니다. 이후 채팅 요청에 사용합니다.
resultObject업로드된 파일 정보입니다.
result.file_idString파일 고유 ID입니다. 파일 삭제 시 사용할 수 있습니다.
result.idNumber내부 파일 ID입니다. 기존 호환성을 위해 포함됩니다.
result.session_idString파일이 연결된 세션 ID입니다.
result.file_nameString업로드된 파일명입니다.
result.content_charsNumber파일에서 추출된 본문 글자 수입니다.
result.summary_charsNumber파일 요약 글자 수입니다.

2. 파일 업로드 후 채팅 흐름

파일 업로드 응답에서 받은 session_id를 사용해 채팅 API를 호출합니다.

1단계. 파일 업로드

JSON
curl -X POST https://api.sidetalk.ai/v1/chat/files \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "file=@청소기매뉴얼.pdf"
응답:
JSON
{
  "success": true,
  "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "result": {
    "file_id": "file_9e17c4df-5b4a-48c8-8e8f-3de7c6e9c5a1",
    "id": 15,
    "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
    "file_name": "청소기매뉴얼.pdf",
    "content_chars": 9527,
    "summary_chars": 247
  }
}

2단계. 같은 session_id로 질문

JSON
curl -X POST https://api.sidetalk.ai/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
    "message": "먼지통 청소 방법 알려줘.",
    "stream": false
  }'
응답:
JSON
{
  "success": true,
  "object": "chat.completion",
  "model": "sidetalk",
  "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "chat_log_uuid": "2b9cc8fb-3cc6-4d40-aef6-d44af3d074f3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "먼지통 청소 방법은 다음과 같습니다..."
      }
    }
  ]
}

3. 파일 목록 조회 API

현재 세션에 연결된 파일 목록을 조회합니다.

URL

Plain Text
https://api.sidetalk.ai/v1/chat/files

HTTP 메서드

Plain Text
GET

헤더

헤더값설명
AuthorizationBearer <api_key>Sidetalk 대시보드에서 제공된 API 키를 사용하세요.

Query Parameters

파라미터타입필수설명
session_idString예조회할 세션 ID입니다.
sessionIdString아니요session_id의 alias입니다.

요청 예시

JSON
curl -X GET "https://api.sidetalk.ai/v1/chat/files?session_id=943f15db-3984-4f21-ad64-f0115839c3a6" \
  -H "Authorization: Bearer ${API_KEY}"

응답 예시

JSON
{
  "success": true,
  "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "files": [
    {
      "file_id": "file_9e17c4df-5b4a-48c8-8e8f-3de7c6e9c5a1",
      "id": 15,
      "file_name": "청소기매뉴얼.pdf",
      "mime_type": "application/pdf",
      "file_size": 3623117,
      "content_chars": 9527,
      "summary_chars": 247,
      "created_at": "2026-07-14T10:20:30.000Z"
    }
  ]
}

4. 파일 삭제 API

현재 세션에 연결된 파일을 삭제합니다.

URL

Plain Text
https://api.sidetalk.ai/v1/chat/files

HTTP 메서드

Plain Text
DELETE

헤더

헤더값설명
Content-Typeapplication/json요청 본문이 JSON 형식임을 나타냅니다.
AuthorizationBearer <api_key>Sidetalk 대시보드에서 제공된 API 키를 사용하세요.

본문

파라미터타입필수설명
session_idString예파일이 연결된 세션 ID입니다.
sessionIdString아니요session_id의 alias입니다.
file_idString아니요삭제할 파일 ID입니다. 없으면 해당 세션의 모든 파일을 삭제합니다.

요청 예시


특정 파일 삭제

JSON
curl -X DELETE https://api.sidetalk.ai/v1/chat/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
    "file_id": "file_9e17c4df-5b4a-48c8-8e8f-3de7c6e9c5a1"
  }'

세션의 모든 파일 삭제

JSON
curl -X DELETE https://api.sidetalk.ai/v1/chat/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6"
  }'

응답 예시

JSON
{
  "success": true,
  "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "deleted": 1
}

5. JavaScript 예시


5-1. 파일 업로드

JavaScript
async function uploadFile(file, sessionId = "") {
  const formData = new FormData();
  formData.append("file", file);

  if (sessionId) {
    formData.append("session_id", sessionId);
  }

  const response = await fetch("https://api.sidetalk.ai/v1/chat/files", {
    method: "POST",
    headers: {
      "Authorization": "Bearer [API_KEY]"
    },
    body: formData
  });

  const data = await response.json();

  if (!response.ok || !data.success) {
    console.error("File Upload Error:", data.error || "Unknown error");
    return null;
  }

  return {
    sessionId: data.session_id,
    file: data.result
  };
}

5-2. 파일 업로드 후 질문

JavaScript
async function askWithFile(file, question) {
  const uploadResult = await uploadFile(file);

  if (!uploadResult) {
    return null;
  }

  const response = await fetch("https://api.sidetalk.ai/v2/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer [API_KEY]"
    },
    body: JSON.stringify({
      session_id: uploadResult.sessionId,
      message: question,
      stream: false
    })
  });

  const data = await response.json();

  if (!response.ok) {
    console.error("Chat Error:", data.error?.message || "Unknown error");
    return null;
  }

  return {
    sessionId: data.session_id,
    file: uploadResult.file,
    answer: data.choices?.[0]?.message?.content || "",
    chatLogUuid: data.chat_log_uuid || ""
  };
}

5-3. 파일 목록 조회

JavaScript
async function getSessionFiles(sessionId) {
  const response = await fetch(
    `https://api.sidetalk.ai/v1/chat/files?session_id=${encodeURIComponent(sessionId)}`,
    {
      method: "GET",
      headers: {
        "Authorization": "Bearer [API_KEY]"
      }
    }
  );

  const data = await response.json();

  if (!response.ok || !data.success) {
    console.error("File List Error:", data.error || "Unknown error");
    return [];
  }

  return data.files || [];
}

5-4. 파일 삭제

JavaScript
async function deleteSessionFile(sessionId, fileId = "") {
  const body = {
    session_id: sessionId
  };

  if (fileId) {
    body.file_id = fileId;
  }

  const response = await fetch("https://api.sidetalk.ai/v1/chat/files", {
    method: "DELETE",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer [API_KEY]"
    },
    body: JSON.stringify(body)
  });

  const data = await response.json();

  if (!response.ok || !data.success) {
    console.error("File Delete Error:", data.error || "Unknown error");
    return null;
  }

  return data;
}

6. 오류 응답

파일 업로드 API에서 오류가 발생하면 다음과 같은 형식으로 반환됩니다.
JSON
{
  "success": false,
  "error": "Only txt, pdf, xlsx, xls, and csv files are allowed."
}

주요 오류 케이스

HTTP 상태error설명
400file is required파일이 누락된 경우
400invalid_session_id_formatsession_id 형식이 잘못된 경우
404session_id_not_found전달한 session_id가 현재 사이트에 존재하지 않는 경우
400Only txt, pdf, xlsx, xls, and csv files are allowed.지원하지 않는 파일 형식인 경우
400File size exceeds limit.파일 크기 제한을 초과한 경우
403Authentication errorAPI 인증에 실패한 경우
500server_error서버 내부 오류가 발생한 경우

7. 참고 사항

  • 파일 업로드 API는 현재 /v1/chat/files 경로를 사용합니다.
  • v2 채팅 API와 함께 사용할 수 있습니다.
  • 파일 업로드 응답에서 받은 session_id를 v2 채팅 API에 전달하면 됩니다.
  • session_id 없이 파일을 업로드하면 서버에서 새 세션을 발급합니다.
  • 여러 파일을 같은 session_id에 연결할 수 있습니다.
  • 채팅 시 AI가 질문과 대화 흐름을 기준으로 파일 참고 여부를 판단합니다.
  • 파일 자체는 장기 저장하지 않고, 문서 파싱 후 추출된 텍스트와 요약 정보만 세션 파일 테이블에 저장됩니다.
  • file_id는 파일 삭제 등 파일 단위 작업에 사용할 수 있습니다.