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

학습용 파일 업로드 API

목적

이 API는 챗봇의 지식(Knowledge) 베이스로 활용될 파일을 업로드합니다. TXT 또는 PDF 형식의 파일을 지원합니다.

URL



HTTP 메서드

POST

헤더

헤더값설명
Content-Typemultipart/form-data파일을 전송하기 위해 반드시 multipart/form-data 형식이어야 합니다.
AuthorizationBearer <api_key>Sidetalk 대시보드에서 설치하기 메뉴에 제공된 API 키를 사용하세요.

파라미터 (Body)

Plain Text
multipart/form-data
형식으로 전송되는 Body 파라미터입니다.
파라미터타입필수설명
fileFile예업로드할 파일 객체입니다. (지원 형식: .txt, .pdf) TXT: 최대 3MB - PDF: 최대 20MB

요청 예시

Bash
curl-XPOST"https://api.sidetalk.ai/v1/knowledge/file"\
-H"Authorization: Bearer ${API_KEY}"\
-F"file=@/path/to/document.pdf"

응답 형식

응답은 JSON 형식으로 제공되며, 파일이 스토리지에 성공적으로 업로드되었음을 의미합니다.
주의: 이 응답은 파일 저장 성공을 의미할 뿐, 지식 데이터 처리가 완료된 것은 아닙니다. AI 데이터 학습 작업은 백그라운드에서 비동기로 진행됩니다.

응답 본문 (성공 시)

JSON
{
	"success":true,
	"result": {
			"file_name":"manual.pdf",
			"file_size":1048576,
			"file_type":"application/pdf"
	  }
}

응답 필드 설명

1. 기본 응답
필드타입설명
successBoolean요청 처리 성공 여부입니다. (true)
2. 결과 데이터 (result)
필드타입설명
file_nameString사용자가 업로드한 원본 파일명입니다.
file_sizeNumber업로드된 파일의 크기(Byte)입니다.
file_typeString업로드된 파일의 MIME 타입입니다. (예: application/pdf)

예시 코드 (JavaScript)

파일 업로드

JavaScript
async function uploadKnowledgeFile(fileObject) {
    const baseUrl = "https://api.sidetalk.ai/v1/knowledge/file";
    
    // FormData 생성
    const formData = new FormData();
    formData.append("file", fileObject); // <input type="file">에서 가져온 File 객체
  
    try {
        const response = await fetch(baseUrl, {
            method: "POST",
            headers: {
                "Authorization": "Bearer [API_KEY]"
                // Content-Type 헤더는 브라우저가 자동으로 multipart/form-data로 설정하므로 생략
            },
            body: formData
        });
        if (!response.ok) {
            const errorData = await response.json();
            console.error("Upload Failed:", errorData.error || 'Unknown error');
            return;
        }
        const result = await response.json();
        console.log("Upload Success:", result);
    } catch (error) {
        console.error("Error uploading file:", error);
    }
}

오류 응답

요청 처리 중 오류가 발생한 경우, success: false 와 함께 에러 메시지가 반환됩니다.

응답 본문

JSON
{
	"success":false,
	"error":"PDF file size must be 20MB or less."
}

오류 메시지 예시

  • No file uploaded or invalid format.: 파일이 첨부되지 않았거나 올바르지 않은 형식일 때
  • Only txt and pdf files are allowed.: 지원하지 않는 확장자일 때
  • Text file size must be 3MB or less.: TXT 파일 용량 초과
  • PDF file size must be 20MB or less.: PDF 파일 용량 초과
  • Invalid text file. Binary content detected.: 텍스트 파일에 바이너리 데이터가 포함된 경우
  • Invalid PDF file. Signature mismatch.: PDF 파일 헤더가 손상되었거나 위조된 경우

오류 응답 필드 설명

필드타입설명
successBoolean요청 처리 실패 여부입니다. (false)
errorString발생한 오류에 대한 상세 정보입니다.