본문으로 건너뛰기

트랜스코딩 관리

트랜스코딩 관리 API v3 레퍼런스 바로가기
버전별 기능 범위 안내
  • v2 미지원: 트랜스코딩 관리 기능은 v2에서 지원하지 않으므로, v1에서 v3로 직접 마이그레이션해야 합니다.
  • 공통 인증: 모든 버전의 API는 쿼리 스트링 파라미터(?access_token=)를 통한 공통 인증 방식을 사용합니다. 에러 핸들링 가이드는 핵심 변경 사항 섹션을 참고하세요.

트랜스코딩 진행 상태 조회​

  • 기존 (v1 - 목록 조회): GET /media/upload_file
  • 기존 (v1 - 단건 조회): GET /media/media_content/view/{media_content_id}
  • 기존 (v2): 미지원
  • 변경 (v3): GET /media-contents/{upload_file_key}/progress
변경 사항
  • 엔드포인트 단일화: v1에서는 목록 조회와 단건 조회 엔드포인트가 분리되어 있었으나, v3에서는 고유 식별자인 upload_file_key 기준의 단건 조회 엔드포인트로 통합되었습니다.
  • 식별자 파라미터 주의: v1의 단건 조회 API는 파라미터로 watcher_file_key를 사용했으나, v3에서는 업로드 파일의 고유 식별자인 upload_file_key를 사용합니다. 마이그레이션 시 매핑에 주의하세요.
트랜스코딩 상태 코드 및 응답 구조 상세

트랜스코딩 상태 코드 (transcoding_stage)​

상태 코드는 v1과 v3가 동일하게 유지됩니다. 상태 코드 11(트랜스코딩 준비 중)은 내부 작업 루프에서 0(대기중) 또는 12(진행 중) 상태를 거친 후 즉각적으로 21(완료) 상태로 전이됩니다.

상태 코드설명
0대기 중
11트랜스코딩 준비 중
1트랜스코딩 시작
12트랜스코딩 중
21트랜스코딩 완료
51트랜스코딩 오류
52초기화 실패

응답 구조 대조​

  • v1 (단건 조회)
{
  "error": 0,
  "message": "success",
  "result": {
    "media_content": { 
      "id": 123, 
      "watcher_file_key": "v1_key", 
      ...
      }
  }
}
  • v3
{
  "status": 200,
  "data": {
    "id": 12345,
    "title": "string",
    "upload_file_key": "string",
    "transcoding_stage": 21,
    "transcoding_stage_name": "Completed",
    "transcoding_progress": 100
  }
}

추가 트랜스코딩 작업 생성​

특정 미디어 콘텐츠에 대하여 추가적인 화질/포맷(Profile)의 트랜스코딩 작업을 수동으로 스케줄링합니다.

  • 기존 (v1): POST /media/library/create_transcoding_file/{upload_file_key} (본문에 profile_key 포함)
  • 기존 (v2): 미지원
  • 변경 (v3): POST /media-contents/{upload_file_key}/media-profiles/{media_profile_key}/transcoding-jobs
변경 사항
  • 파라미터 위치 이동: v1에서 요청 본문에 담아 보내던 대상 프로파일 키(profile_key)가 v3에서는 URL 경로 파라미터(media_profile_key)로 변경되었습니다.
  • 제약 사항 (유지): 이미 진행 중이거나 완료된 파일 프로파일은 추가 트랜스코딩 대상에서 제외됩니다. 이 비즈니스 로직은 v1과 v3가 동일합니다.

응답 구조 대조​

  • v1: { error, message } (생성된 작업 식별자 미제공)
  • v3: { "data": [{ "key": "new_job_key" }], "status": "ok" } (새롭게 생성된 트랜스코딩 작업 식별자 배열 반환)

트랜스코딩 파일 관리 (v3 신규 추가)​

  • 기존 (v1/v2): 미지원
  • 변경 (v3): 신규 엔드포인트 제공

신규 API 엔드포인트 목록​

트랜스코딩 파일은 파일 ID(transcoding_file_id)와 인코딩 프로파일 키(profile_key) 두 가지 식별 체계를 통해 조작할 수 있습니다.

기능HTTPv3 엔드포인트
트랜스코딩 파일 목록 조회GET/media-contents/{upload_file_key}/transcoding-files
트랜스코딩 파일 다운로드 URL 생성GET/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}/download
트랜스코딩 파일 활성화 (파일 ID 기반)PUT/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}/enable
트랜스코딩 파일 활성화 (프로파일 키 기반)PUT/media-contents/{upload_file_key}/media-profiles/{profile_key}/enable
트랜스코딩 파일 비활성화 (파일 ID 기반)PUT/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}/disable
트랜스코딩 파일 비활성화 (프로파일 키 기반)PUT/media-contents/{upload_file_key}/media-profiles/{profile_key}/disable
트랜스코딩 파일 삭제 (파일 ID 기반)DELETE/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}
트랜스코딩 파일 삭제 (프로파일 키 기반)DELETE/media-contents/{upload_file_key}/media-profiles/{profile_key}
응답 구조 상세

트랜스코딩 파일 목록 조회/활성화/비활성화 응답 명세​

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "media_profile_group_name": "PC1(16:9)",
      "media_profile_group_key": "pc1",
      "profile_name": "PC1(16:9) Normal",
      "profile_key": "pc1-normal",
      "filesize_bytes": 133306319,
      "media_information": {
        "file": { ... },
        "video": { ... },
        "audio": { ... }
      },
      "thumbnail_urls": {
        "big": "https://...",
        "small": "https://..."
      },
      "created_at": "2023-10-01T10:00:00Z",
      "updated_at": "2023-10-01T10:05:00Z"
    }
  ]
}

트랜스코딩 파일 다운로드 URL 생성 응답 명세​

{
  "data": {
    "expires": "2026-07-14T09:47:38+00:00",
    "download_url": "https://download.kr.kollus.com/path-to-transcoded-file"
  }
}

트랜스코딩 파일 삭제 응답 명세​

{
  "data": [],
  "status": "ok"
}