Sejong Server API

Veluga API 명세서 (v1)

벨루가에서 제공하는 API 명세서입니다.

공통(Common)

Response Template

벨루가에서 응답하는 모든 Response 템플릿은 아래와 같은 구조를 나타냅니다.
(이벤트 스트림 제외)

필드	타입	필수 여부	설명
success	boolean	Y	응답 성공 여부
data	`object	null`	Y
message	string	Y	응답 관련 메시지
errorCode	`string	null`	Y

Error

벨루가 서비스 이용하면서 다음과 같은 에러가 발생할 수 있습니다.

에러 코드	에러 상태	내용
MISSING_PARAMETER	400	필수 파라미터가 없습니다.
INVALID_PARAMETER	400	파라미터가 잘못되었습니다.
COMMON_SYSTEM_ERROR	500	알 수 없는 오류가 발생했습니다.
COMMON_BAD_REQUEST	400	잘못된 요청 입니다.
COMMON_FAILED_RESPONSE	500	데이터 불러오기에 실패 했습니다.
COMMON_NO_PERMISSION	403	권한이 없습니다.
COMMON_NO_AUTHORIZATION	401	인증이 유효하지 않습니다.
USER_NOT_FOUND	404	유저를 찾을 수 없습니다.
CHANNEL_NOT_FOUND	404	채널을 찾을 수 없습니다.
FILE_NAME_REQUIRED	400	파일 이름을 찾을 수 없습니다.
FILE_EXTENSION_NOT_FOUND	400	파일 확장자를 찾을 수 없습니다.
SESSION_NOT_FOUND	404	세션을 찾을 수 없습니다.
NO_AVAILABLE_USAGE	402	사용량을 모두 소진하였습니다.

학습API

파일 학습 요청

파일 학습을 요청합니다. 업로드 시 AI 서버에 학습 요청을 하고, 학습 결과를 조회하여 AI를 통해 확인할 수 있습니다.

curl -X POST "https://sejong-api.veluga.app/api/v1/document/file" \
     -H "X-VELUGA-API-KEY: [YOUR_API_KEY]" \
     -H "Content-Type: multipart/form-data" \
     -F "channelId=[YOUR_CHANNEL_ID]" \
     -F "file=@[PATH_TO_YOUR_FILE]"

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URL
POST	https://sejong-api.veluga.app/api/v1/document/file

요청 헤더

헤더에 대한 설명은 다음과 같습니다.

헤더	필수 여부	설명
X-VELUGA-API-KEY	Y	벨루가 계정으로 발급받은 API KEY
Content-Type		multipart/form-data

요청 바디

바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
channelId	string	Y	벨루가에서 생성한 채널 ID
file	binary	Y	요청할 파일입니다.
docFilter	object	N	사용자 정의 필터 입니다. 문서 검색에 사용할 인덱스 key를 자유롭게 설정할 수 있습니다. (예: {“tag”: “korea”})
			지원하는 확장자: pdf, txt, docx, md, csv, html, htm

응답

응답 형식을 설명합니다.

응답 헤더

헤더에 대한 설명은 다음과 같습니다.

헤더	필수 여부	설명
Content-Type	-	application/json

응답 데이터

응답 데이터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
data	string	Y	학습 요청한 문서 ID

파일 리스트 조회

학습 요청된 파일 리스트를 조회합니다.

curl -X GET "https://sejong-api.veluga.app/api/v1/document/file" \
     -H "X-VELUGA-API-KEY: [YOUR_API_KEY]" \
     -G \
     -d "channelId=[YOUR_CHANNEL_ID]" \
     -d "keyword=[OPTIONAL_KEYWORD]" \
     -d "page=[PAGE_NUMBER]" \
     -d "limit=[LIMIT_NUMBER]" \
     -d "sortType=[SORT_TYPE]" \
     -d "sort=[SORT_ORDER]"

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URL
GET	https://sejong-api.veluga.app/api/v1/document/file

요청 헤더

헤더에 대한 설명은 다음과 같습니다.

헤더	필수 여부	설명
X-VELUGA-API-KEY	Y	벨루가 계정으로 발급받은 API KEY

요청 파라미터

파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
channelId	string	Y	파일 리스트를 조회할 채널 ID입니다.
keyword	string	N	키워드로 검색할 때 사용하는 필드입니다.
page	number	N	검색할 페이지입니다. (기본값: 1)
limit	number	N	페이지 별 컨텐츠 개수입니다. (기본값: 20)
sortType	string	N	정렬 타입입니다. (기본값: createdAt)
sort	string	N	정렬 순서입니다. (“asc”

응답

응답 형식을 설명합니다.

응답 헤더

헤더에 대한 설명은 다음과 같습니다.

헤더	필수 여부	설명
Content-Type	-	application/json

응답 데이터

응답 데이터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
data	object	Y	응답 데이터입니다.
data.totalCount	number	Y	전체 컨텐츠 개수입니다.
data.page	number	Y	현재 페이지입니다.
data.limit	number	Y	페이지별 컨텐츠 개수입니다.
data.list	array	Y	파일 리스트입니다.
data.list[0]._id	string	Y	파일 ID입니다.
data.list[0].state	string	Y	학습 상태입니다. ("training"
data.list[0].originalName	string	Y	학습 문서 원본 이름입니다.
data.list[0].signedUrl	string	Y	파일 다운로드 링크입니다.
data.list[0].size	number	Y	파일 용량입니다. (MB)
data.list[0].type	string	Y	파일 확장자입니다.
data.list[0].files	array	Y	하위 파일 리스트입니다. (지원하지 않습니다.)

Veluga API 명세서 세종대 V1 20240730 (1).pdf364.82KB

샘플 코드 (Python)

공지사항 API PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://sejong-api.veluga.app/api/v1/document/post',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
"channelId": "66b1f77f6a1a3b4ec211b383",
"title": "공지사항 제목",
"content": "<p>공지사항 내용입니다.</p>",
"board": "공지사항 게시판 보드이름 ",
"fromUrl": "https://example.com/notice",
"regDatetime": "2024-08-13T12:00:00Z",
"metadata":{
"author": "관리자"
},
"attachments": [
{
"name": "2024년 전국의료관련감염감시체계(KONIS) 참여 추가 신청 안내.pdf",
"fileUrl": "https://www.kdca.go.kr/filepath/boardDownload.es?bid=0014&list_no=725306&seq=1"
},
{
"name": "공문KONIS참여신청게시판_사용자매뉴얼(참여기관용).pdf",
"fileUrl": "https://www.kdca.go.kr/filepath/boardDownload.es?bid=0014&list_no=725306&seq=3"
}
],
"docFilter":  {
"docType": "강의계획서"
}
}',
  CURLOPT_HTTPHEADER => array(
    'X-VELUGA-API-KEY: 78712cca19ef5e06192c21b256ce083466e192e291f0cfe8eff4109045e9bf08',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

결과 조회

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://sejong-api.veluga.app/api/v1/document/post/66c460f6dbdd6fb45cef75ea',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'X-VELUGA-API-KEY: 78712cca19ef5e06192c21b256ce083466e192e291f0cfe8eff4109045e9bf08',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

공지사항 (게시물) 삭제 예시

<?php

function get_failed_posts($api_key, $channel_id, $board_name = null, $keyword = null) {
    // 게시물 리스트 조회 API URL 설정
    $list_url = "https://sejong-api.veluga.app/api/v1/document/post";

    // 요청 헤더 설정
    $headers = [
        "X-VELUGA-API-KEY: $api_key",
        "Content-Type: application/json"
    ];

    // 요청 파라미터 설정
    $params = [
        "channelId" => $channel_id,
        "boardName" => $board_name,
        "keyword" => $keyword,
        "page" => 1,
        "limit" => 100, // 최대 100개의 게시물 조회
        "sortType" => "createdAt",
        "sort" => "desc"
    ];

    // 파라미터를 쿼리 스트링으로 변환
    $query = http_build_query($params);

    // cURL 초기화
    $ch = curl_init();

    // cURL 옵션 설정
    curl_setopt($ch, CURLOPT_URL, "$list_url?$query");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    // 요청 실행 및 응답 받기
    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    // cURL 종료
    curl_close($ch);

    // 응답 코드가 200이면 데이터 처리
    if ($http_code == 200) {
        $response_data = json_decode($response, true);
        $failed_posts = array_filter($response_data['data']['list'], function($post) {
            return $post['state'] == 'fail';
        });
        return $failed_posts;
    } else {
        echo "게시물 리스트 조회 실패. 응답 코드: $http_code\n";
        echo "응답 내용: $response\n";
        return null;
    }
}

function delete_failed_post($api_key, $post_id) {
    // 게시물 삭제 API URL 설정
    $delete_url = "https://sejong-api.veluga.app/api/v1/document/$post_id";

    // 요청 헤더 설정
    $headers = [
        "X-VELUGA-API-KEY: $api_key"
    ];

    // cURL 초기화
    $ch = curl_init();

    // cURL 옵션 설정
    curl_setopt($ch, CURLOPT_URL, $delete_url);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    // 요청 실행 및 응답 받기
    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    // cURL 종료
    curl_close($ch);

    // 응답 코드가 200이면 삭제 성공 메시지 출력
    if ($http_code == 200) {
        echo "게시물 삭제 성공. 게시물 ID: $post_id\n";
    } else {
        echo "게시물 삭제 실패. 게시물 ID: $post_id, 응답 코드: $http_code\n";
        echo "응답 내용: $response\n";
    }
}

function delete_all_failed_posts($api_key, $channel_id, $board_name = null, $keyword = null) {
    // 학습이 실패한 게시물 리스트 가져오기
    $failed_posts = get_failed_posts($api_key, $channel_id, $board_name, $keyword);

    if (!empty($failed_posts)) {
        echo "총 " . count($failed_posts) . "개의 학습 실패 게시물이 발견되었습니다.\n";
        foreach ($failed_posts as $post) {
            delete_failed_post($api_key, $post['_id']);
        }
    } else {
        echo "학습 실패한 게시물이 없습니다.\n";
    }
}

?>

php 파일 업로드 샘플 (강제업데이트) 에러체크 까지

<?php

function train_file_and_check_status($api_key, $channel_id, $file_path, $doc_filter = null) {
    // API URL 설정
    $upload_url = "https://sejong-api.veluga.app/api/v1/document/file";
    $check_url_template = "https://sejong-api.veluga.app/api/v1/document/file/{id}";

    // 헤더 설정
    $headers = [
        "X-VELUGA-API-KEY: $api_key"
    ];

    // 데이터 설정
    $post_fields = [
        'channelId' => $channel_id,
        'forceUpdate' => 'true'
    ];

    if ($doc_filter !== null) {
        $post_fields['docFilter'] = json_encode($doc_filter); // doc_filter를 JSON 문자열로 변환
    }

    // 파일 추가
    $post_fields['file'] = curl_file_create($file_path);

    // 파일 업로드 요청
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $upload_url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_fields);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($http_code == 200) {
        $response_data = json_decode($response, true);
        $file_id = $response_data['data'];
        $success = $response_data['success'];

        if (!$success) {
            echo "파일 업로드 실패. 응답 코드: $http_code\n";
            echo "응답 내용: $response\n";
            return;
        }
        echo "파일 업로드 성공. 파일 ID: $file_id\n";

        // 학습 상태 체크 (2초 간격)
        while (true) {
            $check_url = str_replace("{id}", $file_id, $check_url_template);
            $ch = curl_init();
            curl_setopt($ch, CURLOPT_URL, $check_url);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
            
            $check_response = curl_exec($ch);
            $check_http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
            curl_close($ch);

            if ($check_http_code == 200) {
                $check_data = json_decode($check_response, true)['data'];
                $file_state = $check_data['state'];
                
                echo "파일 상태: $file_state\n";
                
                if ($file_state === 'success' || $file_state === 'fail') {
                    echo "학습이 $file_state 상태로 완료되었습니다.\n";
                    break;
                }
            } else {
                echo "학습 상태 체크 실패. 응답 코드: $check_http_code\n";
                break;
            }

            sleep(2); // 2초 대기
        }
    } else {
        echo "파일 업로드 실패. 응답 코드: $http_code\n";
        echo "응답 내용: $response\n";
    }
}

// 예시 사용법
$api_key = 'your_api_key_here';
$channel_id = 'your_channel_id_here';
$file_path = '/path/to/your/file.pdf';  // 실제 파일 경로로 변경하세요
$doc_filter = [
    'docType' => '공지사항'
];

train_file_and_check_status($api_key, $channel_id, $file_path, $doc_filter);

?>

Made with Slashpage