API 레퍼런스

강의 정보와 데이터(자막, 학습 자료 등)를 업로드하고 관리하는 REST API입니다.

공통 사항

Base URL

https://tap-file-upload-production.coxwave.link

인증

모든 API 요청에는 TAP-API-KEY 헤더가 필요합니다.

Request Headers

Parameter	Type	Required	Description
TAP-API-KEY	String	O	발급받은 API 키

데이터 타입

Type	Description	Format
information	강의 정보 메타데이터	JSON
script	강의 자막 파일	SRT, VTT
video	자막 추출용 강의 영상 URL	MP4, AVI, MOV, MKV, WMV, FLV, WEBM, M4V, 3GP, OGV
content	학습 자료 문서	PDF, HTML, PY, IPYNB, TXT

강의 정보

강의의 메타데이터(제목, 설명, 커리큘럼 등)를 등록하고 관리합니다.
강의 정보는 AI 튜터가 학습 컨텍스트를 이해하는 데 필요합니다.

Endpoints

GET/api/v1/coursesGET/api/v1/courses/{course_id}/informationGET/api/v1/courses/{course_id}/clips/{clip_id}/statusPOST/api/v1/courses/informationDELETE/api/v1/courses/{course_id}/information

강의 목록 조회

GET/api/v1/courses#

등록된 강의 목록을 페이지네이션으로 조회합니다.

Request

Query Parameters

Parameter	Type	Required	Description
page	Number	-	페이지 번호 (기본값: 1)
size	Number	-	페이지당 항목 수 (기본값: 10)

Request Example

curl -X GET "https://tap-file-upload-production.coxwave.link/api/v1/courses?page=1&size=10" \
  -H "TAP-API-KEY: {YOUR_API_KEY}"

Response

Parameter	Type	Required	Description
pagination	Object	O	페이지네이션 정보. pagination 참조
courses	Array of objects	O	강의 요약 정보 배열. courses item 참조

pagination

Field	Type	Description
current_page	Number	현재 페이지
page_size	Number	페이지당 항목 수
total_count	Number	전체 항목 수
total_pages	Number	전체 페이지 수
has_next	Boolean	다음 페이지 존재 여부
has_previous	Boolean	이전 페이지 존재 여부

courses item

Field	Type	Description
course_id	String	강의 ID
course_title	String	강의명
course_category	String	강의 카테고리
clip_count	Number	클립 수
total_play_time	Number	총 재생 시간 (초)
upload_date	String	업로드 일자 (YYYY.MM.DD)
script_count	Number	강의자막 개수
content_count	Number	강의자료 개수
has_sections	Boolean	섹션 존재 여부

Response Example

{
  "pagination": {
    "current_page": 1,
    "page_size": 10,
    "total_count": 60,
    "total_pages": 6,
    "has_next": true,
    "has_previous": false
  },
  "courses": [
    {
      "course_id": "1000",
      "course_title": "파이썬 기초 프로그래밍",
      "course_category": "Programming",
      "clip_count": 4,
      "total_play_time": 1800,
      "upload_date": "2025.01.15",
      "script_count": 3,
      "content_count": 8,
      "has_sections": true
    }
  ]
}

강의 정보 조회

GET/api/v1/courses/{course_id}/information#

특정 강의의 상세 정보를 조회합니다.

Request

Path Parameters

Parameter	Type	Required	Description
course_id	String	O	강의 ID

Request Example

curl -X GET "https://tap-file-upload-production.coxwave.link/api/v1/courses/1000/information" \
  -H "TAP-API-KEY: {YOUR_API_KEY}"

Response

Response Fields

Parameter	Type	Required	Description
course_information	Object	O	강의 정보 객체. course_information 참조

course_information

Parameter	Type	Required	Description
material_id	String	O	자료 ID
client_identity	String	O	고객사명
course_id	String	O	강의 ID
course_type	String	-	강의 유형
course_title	String	O	강의 제목
course_description	String	-	강의 설명
course_categories	Array of objects	-	카테고리 목록
total_play_time	Number	O	총 재생 시간 (초)
total_clip_count	Number	O	총 클립 수
instructors	Array of objects	-	강사 목록
course_curriculum	Object	O	커리큘럼
created_at	String	O	생성일시
updated_at	String	-	수정일시

Response Example

{
  "course_information": {
    "material_id": "mat_123",
    "client_identity": "Coxwave",
    "course_id": "1000",
    "course_type": "internet",
    "course_title": "파이썬 기초 프로그래밍",
    "course_description": "파이썬 프로그래밍의 기초를 배우는 강의입니다.",
    "course_categories": [
      {
        "site": "coxwave",
        "course_category_id": "1",
        "course_category_parent_id": "",
        "depth": 0,
        "course_category_title": "Programming"
      }
    ],
    "total_play_time": 1800,
    "total_clip_count": 4,
    "instructors": [
      { "instructor": "콕웨", "instructor_number": "001" }
    ],
    "course_curriculum": {
      "sections": [
        {
          "section_id": "1000_1",
          "section_order": 1,
          "section_title": "Part 1. 파이썬 기초",
          "depth": 1,
          "total_play_time": 900,
          "total_clip_count": 2,
          "clips": [
            {
              "clip_id": "1000_1_1",
              "clip_order": 1,
              "clip_title": "변수 선언",
              "clip_play_time": 450
            }
          ]
        }
      ]
    },
    "created_at": "2025-01-15T10:00:00",
    "updated_at": null
  }
}

클립 상태 조회

GET/api/v1/courses/{course_id}/clips/{clip_id}/status#

특정 클립의 처리 상태를 조회합니다.

Request

Path Parameters

Parameter	Type	Required	Description
course_id	String	O	강의 ID
clip_id	String	O	클립 ID

Request Example

curl -X GET "https://tap-file-upload-production.coxwave.link/api/v1/courses/1000/clips/1000_1_1_1/status" \
  -H "TAP-API-KEY: {YOUR_API_KEY}"

Response

Response Fields

Parameter	Type	Required	Description
clip_id	String	O	클립 ID
status	String	O	처리 상태 (PENDING, PROCESSING, READY)
status_description	String	O	상태에 대한 설명 메시지

Response Example

{
  "clip_id": "1000_1_1_1",
  "status": "READY",
  "status_description": "클립을 사용할 수 있습니다"
}

강의 정보 등록

POST/api/v1/courses/information#

여러 강의의 정보를 한 번에 업로드합니다.

Request

Request Body

Parameter	Type	Required	Description
courses	Array of objects	O	강의 정보 배열. courses item 참조

courses item

Parameter	Type	Required	Description
course_id	String	O	강의 고유 식별자
course_type	String	-	강의 유형 (예: internet)
course_title	String	O	강의 제목
course_description	String	-	강의 설명
total_play_time	Number	O	총 강의 시간 (초)
total_clip_count	Number	O	총 클립 개수
course_categories	Array of objects	-	카테고리 정보 배열
instructors	Array of objects	-	강사 정보 배열
course_curriculum	Object	O	커리큘럼 (sections 또는 clips)

Category 객체

Parameter	Type	Required	Description
site	String	O	사이트명
course_category_id	String	O	카테고리 ID
course_category_parent_id	String	-	부모 카테고리 ID
depth	Number	O	카테고리 깊이 (0부터 시작)
course_category_title	String	O	카테고리명

Instructor 객체

Parameter	Type	Required	Description
instructor	String	O	강사명
instructor_number	String	-	강사 번호

Section 객체

Parameter	Type	Required	Description
section_id	String	O	섹션 고유 식별자
section_order	Number	O	섹션 순서
section_title	String	O	섹션 제목
section_description	String	-	섹션 설명
depth	Number	O	섹션 깊이 (1부터 시작)
total_play_time	Number	O	총 재생 시간 (초)
total_clip_count	Number	O	총 클립 수
sections	Array of objects	-	하위 섹션 (중첩 가능)
clips	Array of objects	-	클립 배열

Clip 객체

Parameter	Type	Required	Description
clip_id	String	O	클립 고유 식별자
clip_order	Number	O	클립 순서
clip_title	String	O	클립 제목
clip_description	String	-	클립 설명
clip_play_time	Number	O	재생 시간 (초)
clip_level	Number	-	난이도 (1: 쉬움, 2: 보통, 3: 어려움)

Section은 clips 또는 sections 중 하나만 가질 수 있습니다.

Request Example

curl -X POST "https://tap-file-upload-production.coxwave.link/api/v1/courses/information" \
  -H "Content-Type: application/json" \
  -H "TAP-API-KEY: {YOUR_API_KEY}" \
  -d '{
    "courses": [
      {
        "course_id": "1000",
        "course_type": "internet",
        "course_title": "파이썬 기초",
        "course_description": "파이썬 프로그래밍 기초 강의",
        "total_play_time": 1800,
        "total_clip_count": 4,
        "instructors": [{ "instructor": "콕웨", "instructor_number": "001" }],
        "course_categories": [
          {
            "site": "coxwave",
            "course_category_id": "1",
            "course_category_parent_id": "",
            "depth": 0,
            "course_category_title": "프로그래밍"
          }
        ],
        "course_curriculum": {
          "sections": [
            {
              "section_id": "1000_1",
              "section_order": 1,
              "section_title": "Part 1. 파이썬 기초",
              "section_description": "파이썬의 기본 문법과 자료형을 배웁니다",
              "depth": 1,
              "total_play_time": 900,
              "total_clip_count": 2,
              "clips": [
                {
                  "clip_id": "1000_1_1",
                  "clip_order": 1,
                  "clip_title": "변수 선언",
                  "clip_description": "파이썬의 변수 선언 방법",
                  "clip_play_time": 450
                },
                {
                  "clip_id": "1000_1_2",
                  "clip_order": 2,
                  "clip_title": "자료형 소개",
                  "clip_description": "기본 자료형(int, str, list, dict)",
                  "clip_play_time": 450
                }
              ]
            },
            {
              "section_id": "1000_2",
              "section_order": 2,
              "section_title": "Part 2. 제어문",
              "section_description": "조건문과 반복문을 배웁니다",
              "depth": 1,
              "total_play_time": 900,
              "total_clip_count": 2,
              "clips": [
                {
                  "clip_id": "1000_2_1",
                  "clip_order": 1,
                  "clip_title": "조건문",
                  "clip_description": "if, elif, else 사용법",
                  "clip_play_time": 450
                },
                {
                  "clip_id": "1000_2_2",
                  "clip_order": 2,
                  "clip_title": "반복문",
                  "clip_description": "for, while 사용법",
                  "clip_play_time": 450
                }
              ]
            }
          ]
        }
      }
    ]
  }'

Response

Response Fields

Parameter	Type	Required	Description
success_courses	Array of strings	O	업로드 성공한 강의 ID 목록
failed_courses	Array of strings	O	업로드 실패한 강의 ID 목록

Response Example

{
  "success_courses": ["1000"],
  "failed_courses": []
}

강의 정보 삭제

DELETE/api/v1/courses/{course_id}/information#

특정 강의의 정보를 삭제합니다.

주의: 강의 정보가 삭제되면 해당 강의와 연관된 모든 데이터 및 기능이 지원되지 않습니다.

Request

Path Parameters

Parameter	Type	Required	Description
course_id	String	O	삭제할 강의 ID

Request Example

curl -X DELETE "https://tap-file-upload-production.coxwave.link/api/v1/courses/1000/information" \
  -H "TAP-API-KEY: {YOUR_API_KEY}"

Response

Response Fields

Parameter	Type	Required	Description
message	String	O	서버 메시지

Response Example

{
  "message": "Course information deleted successfully"
}

강의 데이터

강의에 자막, 학습 자료, 비디오 등을 업로드하고 관리합니다.
업로드된 데이터는 AI 튜터의 답변 품질을 높이는 데 사용됩니다.

Endpoints

GET/api/v1/courses/{course_id}/materialsPOST/api/v1/courses/{course_id}/materialsDELETE/api/v1/courses/{course_id}/materials/{material_id}

강의 자막

강의 영상에서 추출된 자막 데이터입니다. 자막은 AI 튜터의 핵심 학습 데이터입니다.

자막이 있는 경우

Category	Format
Script	SRT, VTT

자막이 없는 경우

자막 원본 파일이 없을 경우, 다음 포맷의 미디어 파일 다운로드 링크(URL)를 제공하시면 콕스웨이브에서 자막 추출을 진행합니다.

Category	Format
Video	MP4, AVI, MOV, MKV, WMV, FLV, WEBM, M4V, 3GP, OGV

강의 자료

강의 수강생에게 제공되는 학습 자료입니다. AI 튜터 연동 필수 항목은 아니지만, 답변 품질 향상을 위해 추가를 권장합니다.

Category	Format
Content	PDF, HTML, PY, IPYNB, TXT

강의 데이터 조회

GET/api/v1/courses/{course_id}/materials#

특정 강의에 업로드된 데이터(자막, 학습 자료 등)를 조회합니다.

Request

Path Parameters

Parameter	Type	Required	Description
course_id	String	O	강의 ID

Query Parameters

Parameter	Type	Required	Description
clip_id	String	-	특정 클립의 데이터만 필터링

Request Example

curl -X GET "https://tap-file-upload-production.coxwave.link/api/v1/courses/1000/materials" \
  -H "TAP-API-KEY: {YOUR_API_KEY}"

Response

Response Fields

Parameter	Type	Required	Description
course_id	String	O	강의 ID
course_title	String	O	강의명
materials	Array of objects	O	업로드된 자료 목록. materials item 참조

materials item

Field	Type	Description
client_identity	String	고객사명
material_id	String	자료 고유 ID
section_id	String	섹션 ID
clip_id	String	클립 ID
type	String	데이터 타입
file_name	String	파일명
size	Number	파일 크기 (bytes)
url	String	파일 URL
status	String	처리 상태
summary	String	콘텐츠 요약
description	String	콘텐츠 설명
is_generated_from_video	Boolean	비디오 URL에서 생성된 자료 여부

Response Example

{
  "course_id": "1000",
  "course_title": "파이썬 기초 프로그래밍",
  "materials": [
    {
      "client_identity": "Coxwave",
      "material_id": "mat_123",
      "section_id": null,
      "clip_id": "1000_1",
      "type": "script",
      "file_name": "lecture1.srt",
      "size": 12345,
      "url": null,
      "status": "EMBEDDED",
      "summary": "파이썬 변수 선언에 대한 강의 내용",
      "description": "파이썬 기초 문법 중 변수 선언 방법을 설명합니다.",
      "is_generated_from_video": false
    }
  ]
}

강의 데이터 등록

POST/api/v1/courses/{course_id}/materials#

강의에 자막, 비디오, 학습 자료를 업로드합니다.

Request

Path Parameters

Parameter	Type	Required	Description
course_id	String	O	강의 ID

Request Body (multipart/form-data)

Parameter	Type	Required	Description
metadata	Array of objects	O	파일 메타데이터 JSON 배열. metadata item 참조
files	Array of files	-	업로드할 파일들 (video 타입 제외)

metadata item

Parameter	Type	Required	Description
clip_id	String	-	클립 ID (clip_id 또는 section_id 중 하나 필수)
section_id	String	-	섹션 ID (섹션 레벨 자료 업로드 시 사용)
type	String	O	데이터 타입 (script, video, content)
file_name	String	O	파일명 또는 비디오 URL

업로드 대상 지정: clip_id 또는 section_id 중 하나를 지정해야 합니다. 둘 다 지정하지 않으면 강의(course) 레벨에 업로드됩니다.

비디오 타입: type: "video"인 경우 파일을 직접 업로드하지 않고 file_name에 비디오 다운로드 URL을 지정합니다. 서버가 해당 URL에서 비디오를 다운로드하여 자막을 자동 추출합니다.

Request Example

curl -X POST "https://tap-file-upload-production.coxwave.link/api/v1/courses/1000/materials" \
  -H "TAP-API-KEY: {YOUR_API_KEY}" \
  -F 'metadata=[
    {"clip_id": "1000_1", "type": "script", "file_name": "script.vtt"},
    {"clip_id": "1000_1", "type": "content", "file_name": "slides.pdf"},
    {"clip_id": "1000_2", "type": "video", "file_name": "https://example.com/video.mp4"}
  ]' \
  -F 'files=@script.vtt' \
  -F 'files=@slides.pdf'

Response

Response Fields

Parameter	Type	Required	Description
course_id	String	O	강의 ID
upload_results	Array of objects	O	업로드 결과 배열. upload_results item 참조

upload_results item

Field	Type	Description
client_identity	String	클라이언트 식별자
material_id	String	자료 고유 ID
section_id	String	섹션 ID (섹션 레벨 자료인 경우)
clip_id	String	클립 ID (클립 레벨 자료인 경우)
file_name	String	파일명
size	Number	파일 크기 (bytes)
status	String	처리 상태
file_log_id	String	파일 로그 ID
is_generated_from_video	Boolean	비디오 URL에서 생성된 자료 여부

Response Example

{
  "course_id": "1000",
  "upload_results": [
    {
      "client_identity": "Coxwave",
      "material_id": "40d2f656-0ea8-41e0-8ea5-fd90da314178",
      "clip_id": "1000_1",
      "file_name": "script.vtt",
      "size": 173,
      "status": "UPLOADING",
      "file_log_id": "6836cf0f767332a07065455a"
    }
  ]
}

강의 데이터 삭제

DELETE/api/v1/courses/{course_id}/materials/{material_id}#

특정 자료를 삭제합니다.

Request

Path Parameters

Parameter	Type	Required	Description
course_id	String	O	강의 ID
material_id	String	O	삭제할 자료 ID

Request Example

curl -X DELETE "https://tap-file-upload-production.coxwave.link/api/v1/courses/1000/materials/mat_123" \
  -H "TAP-API-KEY: {YOUR_API_KEY}"

Response

Response Fields

Parameter	Type	Required	Description
message	String	O	서버 메시지

Response Example

{
  "message": "Material deleted successfully"
}

데이터 처리 상태

업로드된 강의 데이터는 전처리 과정을 거치며, 조회 API의 status 필드로 진행 상황을 확인할 수 있습니다.

Status	Description
UPLOADING	파일 업로드 진행 중
UPLOADED	업로드 완료
UPLOAD_FAILED	업로드 실패
SUMMARIZING	내용 요약 진행 중
SUMMARIZED	요약 완료
SUMMARIZE_FAILED	요약 실패
EMBEDDING	벡터 임베딩 진행 중
EMBEDDED	임베딩 완료
EMBED_FAILED	임베딩 실패
QUIZ_GENERATING	퀴즈 생성 진행 중
QUIZ_GENERATED	퀴즈 생성 완료
QUIZ_GENERATE_FAILED	퀴즈 생성 실패
PING_MESSAGE_GENERATING	추천질문 생성 진행 중
PING_MESSAGE_GENERATED	추천질문 생성 완료 (전체 기능 사용 가능)
PING_MESSAGE_GENERATE_FAILED	추천질문 생성 실패

에러

에러 응답 형식

모든 에러는 다음 형식으로 반환됩니다:

{
  "error_code": "COURSE_NOT_FOUND",
  "message": "존재하지 않는 강의입니다.",
  "status_code": 404
}

에러 코드

HTTP	Error Code	Description	Solution
400	INVALID_COURSE_DATA	유효하지 않은 강의 데이터	요청 데이터 형식 확인
400	EMPTY_CONTENT	비어있는 콘텐츠	필수 필드 확인
401	-	인증 실패	API 키 확인
404	COURSE_NOT_FOUND	존재하지 않는 강의	course_id 확인
404	SECTION_NOT_FOUND	존재하지 않는 섹션	section_id 확인
404	CLIP_NOT_FOUND	존재하지 않는 클립	clip_id 확인
404	MATERIAL_NOT_FOUND	존재하지 않는 자료	material_id 확인
409	DUPLICATE_KEY	중복된 키	이미 존재하는 리소스
500	DATABASE_ERROR	데이터베이스 에러	담당자 문의
500	SERVER_ERROR	서버 내부 에러	담당자 문의

공통 사항

Base URL

인증

Request Headers

데이터 타입

강의 정보

강의 목록 조회

강의 정보 조회

클립 상태 조회

강의 정보 등록

강의 정보 삭제

강의 데이터

강의 자막

강의 자료

강의 데이터 조회

강의 데이터 등록

강의 데이터 삭제

데이터 처리 상태

에러

에러 응답 형식

에러 코드

다음 단계

SDK 가이드

SDK API 레퍼런스

On this page