---
title: "개요"
slug: "vpe-api-overview"
tags: ["Video Player Enhancement"]
updated: 2026-09-17T09:16:48Z
published: 2026-09-17T09:16:48Z
canonical: "api.ncloud-docs.com/vpe-api-overview"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Player Enhancement 개요

Classic/VPC 환경에서 이용 가능합니다.

Video Player Enhancement는 웹 또는 모바일 애플리케이션에서 비디오, 오디오와 같은 미디어 콘텐츠를 재생할 수 있는 네이버 클라우드 플랫폼의 미디어 플레이어 서비스입니다. Video Player Enhancement 서비스에서는 Video Player Management, Media Analytics 관련 기능을 RESTful API 형태로 제공합니다.

## Video Player Enhancement 공통 설정

Video Player Enhancement API에서 공통으로 사용하는 요청 형식과 응답 형식을 설명합니다.

### 요청

공통 요청 형식을 설명합니다.

#### API URL

요청 API URL은 다음과 같습니다.

- Video Player Management

```
https://vpe.apigw.ntruss.com
```
- Media Anaytics

```
https://ma-dashboard-api.vpe.naverncp.com
```

#### 요청 헤더

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

| 필드 | 필수 여부 | 설명 |
| --- | --- | --- |
| `x-ncp-apigw-timestamp` | Required | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간(밀리초) - API Gateway 서버와 5분 이상 시간차 발생 시 유효하지 않은 요청으로 간주 - Unix Timestamp 형식 - [Video Player Management API](/docs/vpe-api-overview#VideoPlayerManagement)에서 사용 |
| `x-ncp-iam-access-key` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key - Access Key 발급 및 확인: [인증키 생성](/docs/common-ncpapi) 참조 - 서브 계정의 Access Key 발급 및 확인: [서브 계정 생성](https://guide.ncloud-docs.com/docs/subaccount-use#%EC%84%9C%EB%B8%8C-%EA%B3%84%EC%A0%95-%EC%83%9D%EC%84%B1) 참조 - [Video Player Management API](/docs/vpe-api-overview#VideoPlayerManagement)에서 사용 |
| `x-ncp-apigw-signature-v2` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명 - Secret Key 발급 및 확인: [인증키 생성](/docs/common-ncpapi) 참조 - 서명 생성: [시그니처 생성](/docs/common-ncpapi) 참조 - [Video Player Management API](/docs/vpe-api-overview#VideoPlayerManagement)에서 사용 |
| `x-ncp-region_code` | Optional | 리전 코드 - `KR`: 한국 (유효 값) - [Video Player Management API](/docs/vpe-api-overview#VideoPlayerManagement)에서 사용 |
| `x-api-key` | Required | API 키 - Media Analytics 대시보드의 **설정 > 기본 설정**에서 **API 키** 확인 - **[API 키 재생성]** 버튼 클릭 시 키가 재발급되며, 이전 키 사용 불가 - [Media Analytics API](/docs/vpe-api-overview#MediaAnalytics)에서 사용 |
| `x-project-id` | Required | 회사 아이디 - Media Analytics 대시보드의 **설정 > 기본 설정**에서 회사 **ID** 확인 - [Media Analytics API](/docs/vpe-api-overview#MediaAnalytics)에서 사용 |
| `Content-Type` | Required | 요청 데이터의 형식 - `application/json` |

### 응답

공통 응답 형식을 설명합니다.

#### 응답 바디

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

**error**

error는 API 호출 실패 정보를 정의합니다. error에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `error` | Object | - | 오류 코드 및 메시지 |
| `error.errorCode` | String | Required | 오류 코드 |
| `error.message` | String | Required | 오류 메시지 |

#### 응답 상태 코드

응답 상태 코드에 대한 설명은 다음과 같습니다.

| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
| --- | --- | --- | --- |
| 200 | 200 | ok | 호출 성공 |
| 200 | 200 | Unauthorized | 서비스 이용이 신청되지 않은 상태 |
| 200 | 4100 | No version information. | 플레이어 버전 정보 없음 |
| 200 | 4601 | - Query string player_no is missing. - Query string sessionId is missing. | - 입력한 플레이어 번호 오류 - 입력한 세션 아이디 오류 |
| 200 | 4602 | Session detail data is empty. | 입력한 세션이 유효하지 않음 |
| 200 | 4610 | Query string name is invalid. | 입력한 이름 오류 |
| 200 | 4700 | Body (JSON) name is missing. | 요청 바디 이름 누락 |
| 200 | 4702 | Body (JSON) domains is missing. | 요청 바디 도메인 누락 |
| 200 | 4703 | Some domains in Body (JSON) domains are invalid. (if type is web) | 요청 바디의 일부 도메인 오류(웹 타입인 경우) |
| 200 | 4705 | Some types in Body (JSON) domains are invalid. | 요청 바디 도메인의 일부 유형 오류 |
| 200 | 4706 | Enter an option value for Body (JSON). | 요청 바디에 옵션 값 입력 필요 |
| 200 | 4707 | Body (JSON) pricing is missing or invalid. | 요청 바디에 pricing 누락되거나 유효하지 않음 |
| 200 | 4708 | There are duplicate domains in Body (JSON) domains. | 요청 바디에 중복된 도메인 존재 |
| 200 | 4709 | Up to 5 domains can be added to Body (JSON) domains. | 요청 바디에 도메인은 최대 5개까지만 추가 가능 |
| 200 | 4711 | Only 1 Body (JSON) app per OS can be added. | 요청 바디에 운영체제당 앱은 1개만 추가 가능 |
| 200 | 4712 | At least 1 Body (JSON) web domain must be added. | 요청 바디에 웹 도메인이 1개 이상 추가되어야 함 |
| 200 | 4713 | Body (JSON) name or web domains cannot be edited. | 요청 바디의 이름 또는 웹 도메인은 수정 불가 |
| 200 | 4729 | Body (JSON) customBtns must be array. | `customBtns` 필드는 배열 타입이어야 함 |
| 200 | 4730 | Body (JSON) customBtns is up to 4. | `customBtns` 필드는 최대 4개까지만 설정 가능 |
| 200 | 4731 | Body (JSON) customBtns position is invalid. | `customBtns` 필드의 포지션이 유효하지 않음 |
| 200 | 4732 | Body (JSON) customBtns position is required. | `customBtns` 필드의 포지션 누락 |
| 200 | 4733 | Body (JSON) customBtns icon is required. | `customBtns` 필드의 아이콘 누락 |
| 200 | 4734 | Body (JSON) customBtns ui is required. | `customBtns` 필드의 UI 누락 |
| 200 | 4735 | Body (JSON) customBtns ui is invalid. | `customBtns` 필드의 UI가 유효하지 않음 |
| 200 | 4736 | Body (JSON) customBtns flow is invalid. | `customBtns` 필드의 플로우가 유효하지 않음 |
| 200 | 4799 | Enter an option value for Body (JSON). | 요청 바디에 옵션 값 입력 필요 |
| 200 | 4800 | No player has been added. | 플레이어가 추가되지 않음 |
| 200 | 4801 | No player information. | 플레이어 정보 없음 |
| 200 | 4802 | This player already exists. | 이미 존재하는 플레이어 |
| 200 | 4803 | The number of players exceeded the limit. | 무료인 경우 1개로 제한 |
| 200 | 4804 | The feature can't be used in the free version of player. | 무료 버전에서 사용 불가 |
| 200 | 4805 | The player name already exists. | 이미 존재하는 플레이어 이름 |
| 400 | 100 | when page_no is too large, the error msg is page_no exceeds the size limit. when page_size is too large, the error msg is page_size exceeds the size limit. | 페이지 번호가 너무 크거나 페이지 크기가 너무 큼 |
| 400 | 4602 | The query duration exceeds the maximum allowed period of {time} hours. | 조회 기간이 최대 허용 기간인 `time` 시간 초과 |
| 400 | 4603 | The query duration exceeds the maximum allowed limit. | 조회 기간이 최대 허용치 초과 |
| 400 | 4604 | The startDate must be earlier than the endDate. | 시작일(`startDate`)은 종료일(`endDate`)보다 이전 날짜여야 함 |
| 401 | 200 | Authentication Failed | 인증 실패 |
| 401 | 210 | Permission Denied | 권한 없음 |
| 404 | 300 | Not Found Exception | 권한 없음 |
| 429 | 400 | Quota Exceeded | Quota 초과 |
| 429 | 410 | Throttle Limited | Rate 초과 |
| 429 | 420 | Rate Limited | Rate 초과 |
| 413 | 430 | Request Entity Too Large | 요청 엔티티 크기 초과 |
| 503 | 500 | Endpoint Error | 엔드포인트 연결 오류 |
| 504 | 510 | Endpoint Timeout | 엔드포인트 연결 시간 초과 |
| 500 | 900 | Unexpected Error | 예외 처리가 안된 오류 |

참고

네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [Ncloud API 응답 상태 코드](/docs/common-ncpapi#3%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오.

#### 응답 예시

호출이 성공한 경우의 응답 예시는 각 API 명세에서 확인해 주십시오. 호출이 실패한 경우의 응답 예시는 다음과 같습니다.

```
{
    "error":{
        "errorCode":"210",
        "message":"Permission Denied"
    }
}
```

## Video Player Enhancement API

Video Player Enhancement 서비스에서 제공하는 API에 대한 설명은 다음과 같습니다.

### Video Player Management

Video Player Management 관련 API에 대한 설명은 다음과 같습니다.

| API | 설명 |
| --- | --- |
| [플레이어 생성](/docs/vpe-api-create) | 웹 또는 모바일 애플리케이션에서 미디어 콘텐츠를 재생할 수 있는 플레이어 생성 |
| [플레이어 복제](/docs/vpe-api-clone) | 기존 플레이어를 복제하여 새 플레이어 생성 |
| [플레이어 SDK 버전 조회](/docs/vpe-api-versions) | 사용 가능한 플레이어 SDK 버전 조회 |
| [플레이어 이름 체크](/docs/vpe-api-check-name) | 플레이어 이름 유효성 및 중복 여부 확인 |
| [플레이어 목록 조회](/docs/vpe-api-list) | 플레이어 정보 목록 조회 |
| [플레이어 옵션 조회](/docs/vpe-api-option) | 플레이어 옵션 정보 조회 |
| [플레이어 조회](/docs/vpe-api-view) | 플레이어 상세 정보 조회 |
| [플레이어 롤백(Develop)](/docs/vpe-api-option-reset) | Develop(개발) 환경에 배포한 플레이어 설정 롤백 |
| [플레이어 배포(Develop)](/docs/vpe-api-deploy-dev) | Develop(개발) 환경에 플레이어 설정 배포 |
| [플레이어 배포(Production)](/docs/vpe-api-deploy-prd) | Production(리얼) 환경에 플레이어 설정 배포 |
| [플레이어 수정](/docs/vpe-api-update) | Production(리얼) 환경에 플레이어의 사이트 도메인 수정 배포 |
| [플레이어 삭제](/docs/vpe-api-delete) | 플레이어 삭제 |

### Media Analytics

Media Analytics 관련 API에 대한 설명은 다음과 같습니다.

| API | 설명 |
| --- | --- |
| [세션 상세 조회](/docs/vpe-api-sessionrecent-uuid) | 플레이어 사용자의 세션 상세 정보 조회 |
| [세션 최근 목록 조회](/docs/vpe-api-sessionrecent) | 플레이어 사용자의 최근 세션 최대 100개 조회 |
| [실시간 시청자 수 조회](/docs/vpe-api-currentviewers) | 실시간 시청자 수를 1분 단위로 조회 |
| [유니크 사용자 수 조회](/docs/vpe-api-uniqusercnt) | 플레이어 사용자(IP 주소 기준) 합계 조회 |
| [전체 재생 수 조회](/docs/vpe-api-playcnt) | 플레이어 재생 횟수 합계 조회 |
| [전체 재생 시간 조회](/docs/vpe-api-playtimesum) | 플레이어 재생 시간 합계 조회 |
| [콘텐츠 재생 목록 조회](/docs/vpe-api-contentssummary) | 플레이어에서 재생한 콘텐츠 목록 조회 |
| [콘텐츠 재생 시간 조회](/docs/vpe-api-contentssummary-playtimetop10) | 플레이어에서 재생한 콘텐츠 중 재생 시간 상위 10개 조회 |
| [콘텐츠 재생 횟수 조회](/docs/vpe-api-contentssummary-playcounttop10) | 플레이어에서 재생한 콘텐츠 중 재생 횟수 상위 10개 조회 |

## Video Player Enhancement 연관 리소스

Video Player Enhancement API에 대한 사용자의 이해를 돕기 위해 다양한 연관 리소스를 제공하고 있습니다.

- Video Player Enhancement API 사용 방법
  - [서명(시그니처) 생성](/docs/common-ncpapi): 요청 헤더에 추가할 서명 생성 방법
  - [Sub Account 사용 가이드](https://guide.ncloud-docs.com/docs/subaccount-overview): 요청 헤더에 추가할 Access Key 발급 방법
  - [Ncloud 공통 응답 상태 코드](/docs/common-ncpapi#3%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C): Video Player Enhancement 서비스에서 사용하는 네이버 클라우드 플랫폼의 공통 응답 상태 코드 정보
- Video Player Enhancement 서비스 사용 방법
  - [Video Player Enhancement 사용 가이드](https://guide.ncloud-docs.com/docs/vpe-overview): 네이버 클라우드 플랫폼 콘솔에서 Video Player Enhancement 서비스를 사용하는 방법
  - [Ncloud 사용 환경 가이드](https://guide.ncloud-docs.com/docs/environment-environment-1-1): VPC, Classic 환경 및 지원 여부에 대한 가이드
  - [요금 소개, 특징, 상세 기능](https://www.ncloud.com/product/media/videoPlayerEnhancement): Video Player Enhancement 서비스의 요금 체계, 특징, 상세 기능 요약
  - [서비스 최신 소식](https://www.ncloud.com/intro/news?categoryCode=MEDIA&serviceCode=SV_0228): Video Player Enhancement 서비스 관련 최신 소식
  - [자주 하는 질문](https://www.ncloud.com/support/faq/prod?categoryCode2=MEDIA&categoryCode3=SV_0228&page=1): Video Player Enhancement 서비스 사용자들이 자주 하는 질문
  - [문의하기](https://www.ncloud.com/support/question/general): API 가이드를 통해서도 궁금증이 해결되지 않는 경우 직접 문의