본문으로 건너뛰기

자막 관리

자막 관리 API v3 레퍼런스 바로가기
공통 변경 사항 안내
  • 공통 변경 사항: v1에서는 주로 POST 메서드와 요청 본문을 사용했으나, v2 및 v3부터는 URL 경로(Path) 기반의 REST API 구조로 전환되었습니다. v2 URL에 포함되어 있던 /vod 프리픽스는 v3에서 제거되었으며, 언어 식별자는 정수형인 language_id에서 문자열 형태의 language_code(예: ko)로 변경되었습니다.
  • 공통 인증: 모든 버전의 API는 쿼리 스트링 파라미터(?access_token=)를 통한 공통 인증 방식을 사용합니다. 에러 판정 기준에 대한 공통 명세는 API v3 마이그레이션 가이드의 핵심 변경 사항 섹션을 참고하세요.

자막 목록 조회​

  • 기존 (v1): POST /media/subtitle/index
  • 기존 (v2): GET /vod/media-contents/{upload_file_key}/subtitles
  • 변경 (v3): GET /media-contents/{upload_file_key}/subtitles
변경 사항
  • HTTP 메서드 전환: POST 메서드(요청 본문 전송)에서 GET 메서드(경로 파라미터 전송)로 변경되었습니다.
  • 식별자 파라미터 변경: v1의 media_content_key 파라미터가 v3에서는 upload_file_key로 변경되었습니다.
  • 필드명 매핑: 식별자 키가 subtitle_id에서 id로, 언어 키가 language_id에서 language_code로, subtitle_url이 srt_url로 각각 명칭이 변경되었습니다.
요청 파라미터 및 응답 구조 상세

요청 쿼리 파라미터​

파라미터데이터 타입설명 및 허용값
nameString자막 이름 필터링
language_codeString자막 언어 필터링 (ko: 한국어, en: 영어)
statusInteger자막 공개 설정 필터링 (0: 비공개, 1: 공개)

응답 구조 대조​

  • v1
{
  "error": 0,
  "result": {
    "subtitle_id": 123,
    "name": "...",
    "language_id": 1,
    "subtitle_url": "...",
    "vtt_url": "..."
  }
}
  • v2/v3
{
  "data": [
    {
      "id": 1234,
      "name": "subtitle1",
      "kind": "main",
      "status": true,
      "language_code": "ko",
      "vtt_url": "https://...",
      "srt_url": "https://...",
      "position": 1
    }
  ]
}
  • 참고: 시스템 내부에서 .srt 파일을 .vtt 포맷으로 자동 변환하는 기능을 제공하지 않습니다. vtt_url 필드에 값이 응답되게 하려면 반드시 확장자가 .vtt인 파일을 직접 업로드해야 합니다.

자막 등록 (텍스트 직접 입력)​

  • 기존 (v1): 미지원 (파일 업로드 방식만 제공)
  • 기존 (v2): POST /vod/media-contents/{upload_file_key}/subtitles
  • 변경 (v3): POST /media-contents/{upload_file_key}/subtitles
요청 본문 상세

요청 본문​

필드데이터 타입필수 여부설명 및 허용값
bodyString필수실제 자막 텍스트
typeString필수자막 파일 규격 (vtt 또는 srt)
kindString필수자막 유형 (main: 메인 자막, sub: 서브 자막)
statusInteger선택자막 공개 설정 (0: 비공개, 1: 공개)
nameString필수자막 이름
language_codeString필수자막 언어 코드 (ko: 한국어, en: 영어)

자막 파일 신규 업로드​

  • 기존 (v1): POST /media/subtitle/upload
  • 기존 (v2): POST /vod/media-contents/{upload_file_key}/subtitles/upload
  • 변경 (v3): POST /media-contents/{upload_file_key}/subtitles/upload
변경 사항
  • 요청 포맷 변경: multipart/form-data 형식을 사용하며, v1에서 전달하던 language_id 대신 language_code를 전송해야 합니다.
  • 응답 데이터 명세 고도화: v1은 성공 시 생성된 식별자만 { "result": { "subtitle_id" } } 형태로 반환했으나, v2 및 v3는 등록된 자막 객체 전체(자막 목록 조회 응답 스펙과 동일)를 반환합니다.
요청 본문 상세

요청 본문 (Multipart Body)​

필드데이터 타입필수 여부설명
fileBinary필수자막 파일
nameString선택자막 이름
language_codeString필수자막 언어 코드
kindString필수자막 유형 (main: 메인 자막, sub: 서브 자막)
statusInteger선택자막 공개 설정 (0: 비공개, 1: 공개)

자막 파일 업데이트​

  • 기존 (v1): POST /media/subtitle/update
  • 기존 (v2): POST /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}/upload
  • 변경 (v3): POST /media-contents/{upload_file_key}/subtitles/{subtitle_id}/upload
기능 안내

multipart/form-data 규격을 사용하며, 요청 본문의 파라미터 스펙은 자막 파일 신규 업로드 항목과 완전히 동일합니다. 요청 시 status 필드를 생략할 경우 기존 설정값이 그대로 유지되며, 응답은 업데이트된 자막 객체 정보를 반환합니다.

자막 정보 조회​

  • 기존 (v1): 미지원
  • 기존 (v2): GET /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}
  • 변경 (v3): GET /media-contents/{upload_file_key}/subtitles/{subtitle_id}
응답 구조 상세

응답 구조 명세​

v3의 경우 시스템 구현에 따라 status(자막 공개 여부) 속성이 포함될 수 있습니다.

{
  "data": {
    "id": 0,
    "name": "string",
    "kind": "string",
    "language_code": "string",
    "vtt_url": "string",
    "srt_url": "string",
    "position": 0
  }
}

자막 정보 수정​

  • 기존 (v1): POST /media/subtitle/update
  • 기존 (v2): PUT /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}
  • 변경 (v3): PUT /media-contents/{upload_file_key}/subtitles/{subtitle_id}
변경 사항
  • 엔드포인트 분리: v1에서는 파일 교체(Upload) 기능과 메타 속성 수정(Update) 기능을 하나의 엔드포인트에서 처리했으나, v3부터는 HTTP PUT 메서드를 사용하는 별도의 API로 완전히 분리되었습니다.
  • 요청 파라미터: 자막 등록 (텍스트 직접 입력)의 요청 본문 파라미터 명세(body, type, kind, name, language_code, status)와 동일한 구조를 사용합니다.

자막 삭제​

  • 기존 (v1): POST /media/subtitle/delete
  • 기존 (v2): DELETE /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}
  • 변경 (v3): DELETE /media-contents/{upload_file_key}/subtitles/{subtitle_id}
변경 사항
  • HTTP 메서드 전환: HTTP 메서드가 POST에서 DELETE로 변경되었습니다.
응답 구조 상세

응답 구조 대조​

  • v1: { "error": 0, "message": "...", "result": true | false }
  • v2: HTTP 204 No Content
  • v3: 성공 시 빈 데이터 배열 구조인 { "data": [] }를 반환합니다.

자막 표시 순서 변경​

변경 사항

v2에서는 특정 자막을 기준으로 앞/뒤(상대적 위치)로 이동하는 방식을 채택했으나, v3에서는 목표 위치를 직접 지정하여 교체하는 방식과 최상단/최하단으로 이동시키는 방식으로 변경되었습니다.

동작 구분v2v3
특정 위치미지원PUT .../subtitles/{subtitle_id}/move
  • (요청 본문) id: 목표 위치의 자막 ID
특정 자막 앞/뒤
  • PUT .../move-before
  • PUT .../move-after
미지원
최상단PUT .../move-firstPUT .../move-first
최하단PUT .../move-lastPUT .../move-last

응답 구조 명세​

변경된 순서값이 반영된 해당 자막의 상세 데이터(자막 목록 조회 응답 스펙과 동일) 객체를 반환합니다.

자막 지원 언어 목록 조회​

  • 기존 (v1): GET /media/subtitle/languages
  • 기존 (v2): GET /vod/languages
  • 변경 (v3): GET /languages
변경 사항

v3에서는 use_subtitle 파라미터(true 또는 false)를 쿼리로 제공하여 자막용 언어만 필터링하여 조회할 수 있습니다.

응답 구조 상세

응답 구조 대조​

  • v1: { "error": 0, "message": "...", "result": object }
  • v2: { "data": [{ "name": "...", "code": "..." }] }
  • v3: { "data": [ApiCommonLanguage object] } (API 레퍼런스의 언어 목록 조회를 참고하세요.)