--- title: "플레이어 옵션 조회" slug: "vpe-api-option" tags: ["Video Player Enhancement"] updated: 2026-09-17T09:16:48Z published: 2026-09-17T09:16:48Z canonical: "api.ncloud-docs.com/vpe-api-option" --- > ## 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. # 플레이어 옵션 조회 Classic/VPC 환경에서 이용 가능합니다. 플레이어에 설정한 옵션 정보를 조회합니다. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | GET | /api/v1/players/{player_no}/options | ### 요청 헤더 Video Player Enhancement API에서 공통으로 사용하는 헤더에 대한 정보는 [Video Player Enhancement 요청 헤더](/docs/vpe-api-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오. ### 요청 경로 파라미터 요청 경로 파라미터에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `player_no` | String | Required | 플레이어 번호 - [플레이어 목록 조회](/docs/vpe-api-list) 참조 | ### 요청 예시 요청 예시는 다음과 같습니다. ``` curl --location --request GET 'https://vpe.apigw.ntruss.com/api/v1/players/6144/options' \ --header 'x-ncp-apigw-timestamp: {Timestamp}' \ --header 'x-ncp-iam-access-key: {Access Key}' \ --header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \ --header 'Content-Type: application/json' \ --header 'x-ncp-region_code: KR' ``` ## 응답 응답 형식을 설명합니다. ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `code` | String | - | 응답 코드 | | `message` | String | - | 응답 메시지 | | `result` | Object | - | 응답 결과 | | `result.env` | String | - | 배포 환경 | | `result.option` | Object | - | 플레이어 옵션 정보 - Standard 요금제: 전체 옵션 지원 - Basic 요금제: 일부 옵션 지원 | | `result.option.touchGestures` | Boolean | - | 터치 제스처 사용 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 | | `result.option.autostart` | Boolean | - | 자동 재생 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 - Basic 요금제에서 사용 가능 | | `result.option.controlBtn` | Object | - | 컨트롤바 버튼 설정 | | `result.option.controlBtn.fullscreen` | Boolean | - | 풀스크린(전체 화면) 버튼 표시 여부 - `true` \| `false` - `true`: 표시 - `false`: 표시 안 함 | | `result.option.controlBtn.pictureInPicture` | Boolean | - | PIP(미니 플레이어 전환) 버튼 표시 여부 - `true` \| `false` - `true`: 표시 - `false`: 표시 안 함 | | `result.option.controlBtn.volume` | Boolean | - | 볼륨 조절 버튼 표시 여부 - `true` \| `false` - `true`: 표시 - `false`: 표시 안 함 | | `result.option.controlBtn.play` | Boolean | - | 플레이 버튼 표시 여부 - `true` \| `false` - `true`: 표시 - `false`: 표시 안 함 | | `result.option.controlBtn.times` | Boolean | - | 시간 표시 여부 - `true` \| `false` - `true`: 표시 - `false`: 표시 안 함 - 전체 영상 길이 및 현재 재생 시간 표시 | | `result.option.controlBtn.setting` | Boolean | - | 설정 버튼 표시 여부 - `true` \| `false` - `true`: 표시 - `false`: 표시 안 함 - 영상 해상도 및 배속 설정 버튼 표시 | | `result.option.controlBtn.subtitle` | Boolean | - | 자막 선택 버튼 표시 여부 - `true` \| `false` - `true`: 표시 - `false`: 표시 안 함 | | `result.option.controlBtn.progressBar` | Boolean | - | 재생바 표시 여부 - `true` \| `false` - `true`: 표시 - `false`: 표시 안 함 | | `result.option.autoPause` | Boolean | - | 브라우저 비활성 시 자동 정지 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 - Basic 요금제에서 사용 가능 | | `result.option.seekingPreview` | Boolean | - | 구간 이동 미리 보기 표시 여부 - `true` \| `false` - `true`: 표시 - `false`: 표시 안 함 | | `result.option.descriptionNotVisible` | Boolean | - | 디스크립션(영상 제목 및 메타데이터 UI 표시) 사용 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 | | `result.option.playRateSetting` | Array | - | 재생 배속 옵션 목록 | | `result.option.repeat` | Boolean | - | 반복 재생 여부 - `true` \| `false` - `true`: 반복 - `false`: 반복 안 함 - Basic 요금제에서 사용 가능 | | `result.option.startMutedInfoNotVisible` | Boolean | - | 재생 시작 시 음소거 여부 - `true` \| `false` - `true`: 음소거 - `false`: 소리 재생 | | `result.option.ui` | String | - | 컨트롤 UI 유형 - `all` \| `mobile` \| `pc` - `all`: 자동 변환 - `mobile`: 모바일 - `pc`: PC | | `result.option.aspectRatio` | String | - | 화면비 - Basic 요금제에서 사용 가능 | | `result.option.controlActiveTime` | Integer | - | 컨트롤바 자동 숨김 시간(밀리초) - Basic 요금제에서 사용 가능 | | `result.option.muted` | Boolean | - | 음소거 알림창 표시 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 - Basic 요금제에서 사용 가능 | | `result.option.controls` | Boolean | - | 컨트롤바 사용 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 - Basic 요금제에서 사용 가능 | | `result.option.progressBarColor` | String | - | 컨트롤바 컬러 | | `result.option.keyboardShortcut` | Boolean | - | 키보드 단축키 사용 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 | | `result.option.objectFit` | String | - | 화면 채움 방식 - `contain` \| `cover` \| `fill` - `contain`: 비율 맞춤 - `cover`: 비율 맞춤+꽉 채움 - `fill`: 비율 무시+꽉 채움 - Basic 요금제에서 사용 가능 | | `result.option.lowLatencyMode` | Boolean | - | 초저지연 모드 사용 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 - 사용 시 라이브 영상을 항상 최신 구간으로 유지 | | `result.option.lang` | String | - | 언어 설정 - `auto` \| `ko` \| `en` \| `ja` - `auto`: 자동 - `ko`: 한국어 - `en`: 영어 - `ja`: 일본어 - Basic(무료) 요금제에서 사용 가능 | | `result.option.visibleWatermark` | Boolean | - | 텍스트 워터 마크 사용 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 | | `result.option.iosFullscreenNativeMode` | Boolean | - | iOS 모바일 사파리에 대응하는 풀스크린(전체 화면) 모드 설정 지원 여부 - `true` \| `false` - `true`: 지원 - `false`: 지원 안 함 - 1.1.5 버전 이상 또는 최신 버전만 지원 | | `result.option.customBtns` | Array | - | 커스텀 버튼 설정: [customBtns](/docs/vpe-api-option#customBtns) | | `result.option.watermarkConfig` | Object | - | 텍스트 워터 마크 상세 옵션 설정 | | `result.option.watermarkConfig.randPosition` | Boolean | - | 위치 랜덤 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 | | `result.option.watermarkConfig.randPositionInterVal` | Integer | - | 노출 인터벌(밀리초) - `option.watermarkConfig.randPosition`이 `true`인 경우, 유효 값 표시 | | `result.option.watermarkConfig.x` | Integer | - | 수평 오프셋(백분율) - 0~100 - 워터 마크의 가로 위치 값 - `option.watermarkConfig.randPosition`이 `false`인 경우, 유효 값 표시 | | `result.option.watermarkConfig.y` | Integer | - | 수직 오프셋(백분율) - 워터 마크의 세로 위치 값 - `option.watermarkConfig.randPosition`이 `false`인 경우, 유효 값 표시 | | `result.option.watermarkConfig.opacity` | Float | - | 투명도 - 숫자가 높을수록 불투명 - `option.watermarkConfig.randPosition`이 `false`인 경우, 유효 값 표시 | | `result.option.layout` | Array | Optional | 컨트롤바 레이아웃 설정 (SDK Version V2 이상만 지원) | #### `customBtns` `customBtns`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `ui` | String | - | 버튼 UI 환경 - `pc` \| `mobile` - `pc`: PC - `mobile`: 모바일 | | `flow` | String | - | 생성 위치 - `left` \| `right` - `left`: 왼쪽 - `right`: 오른쪽 - `position` 위치에 기존 버튼 존재 시 해당 버튼의 왼쪽 또는 오른쪽에 생성 | | `position` | String | - | 버튼 위치 - `left-top` \| `left-bottom` \| `right-top` \| `right-bottom` - `left-top`: 좌측 상단 - `left-bottom`: 좌측 하단 - `right-top`: 우측 상단 - `right-bottom`: 우측 하단 | | `icon` | String | - | 버튼 이미지 URL | ### 응답 상태 코드 Video Player Enhancement API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [Video Player Enhancement 응답 상태 코드](/docs/vpe-api-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오. ### 응답 예시 응답 예시는 다음과 같습니다. ``` { "code": "200", "message": "ok", "result": { "env": "dev", "option": { "touchGestures": true, "autostart": true, "controlBtn": { "fullscreen": true, "pictureInPicture": true, "volume": true, "play": true, "times": true, "setting": true, "subtitle": false, "progressBar": true }, "autoPause": true, "seekingPreview": true, "descriptionNotVisible": false, "playRateSetting": [ 0.5, 1, 1.5, 2, 2.5 ], "repeat": false, "startMutedInfoNotVisible": false, "ui": "pc", "aspectRatio": "16/9", "controlActiveTime": 3000, "muted": false, "controls": true, "progressBarColor": "#4299f5", "keyboardShortcut": true, "objectFit": "cover", "lowLatencyMode": false, "lang": "ko", "visibleWatermark": true, "customBtns": [ { "ui": "pc", "flow": "left", "position": "right-bottom", "icon": "{Icon URL}" } ], "watermarkConfig": { "randPosition": true, "randPositionInterVal": 60000, "x": null, "y": null, "opacity": null } } } } ```