Preset 생성

VOD Transcoder는 고객이 원하는 다양한 조합으로 Custom preset을 생성하기 위한 API를 제공하며, 생성한 Custom preset의 확인을 위해 Preset 목록 조회 API와 Preset 정보 조회 API를 제공합니다.


VOD Transocder API v2는 안정적인 처리를 위해 초당 12회로 요청 수를 제한하고 있습니다.

요청

POST https://vodtranscoder.apigw.ntruss.com/api/v2/presets

요청 헤더

헤더명 설명
x-ncp-apigw-timestamp 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타내며 API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주
x-ncp-apigw-timestamp:{Timestamp}
x-ncp-apigw-api-key APIGW에서 발급받은 키 값
x-ncp-apigw-api-key:{API Gateway API Key}
x-ncp-iam-access-key 네이버 클라우드 플랫폼 포털에서 발급받은 Access Key ID 값
x-ncp-iam-access-key:{Sub Account Access Key}
x-ncp-apigw-signature-v2 Access Key ID 값과 Secret Key로 암호화한 서명
x-ncp-apigw-signature-v2:{API Gateway Signature}
Content-Type Request body content type을 application/json으로 지정
Content-Type: application/json

요청 바디

API 요청 시 필드명의 대소문자 구분이 필요합니다.

필드명 필수 여부 타입 제약 사항 설명
name Yes String 영문, 숫자, “:“, “-”, “_” 허용, 3자 이상 20자 이하 생성할 Custom preset의 이름
format Yes String MP3, MP4 변환된 미디어 파일 컨테이너 포맷
MP3로 설정 시 presetType이 AUDIO인 Custom preset만 생성할 수 있습니다.
presetType No String NORMAL, AUDIO 생성할 Custom preset의 타입
비디오와 오디오를 포함하는 NORMAL 프리셋 혹은 오디오 스트림만 포함하는 AUDIO 프리셋을 선택할 수 있습니다.
미 지정시 기본값으로 NORMAL 설정
audio Yes Object 트랜스코딩 오디오 옵션 설정 객체입니다.
audio.codec Yes String AAC, MP3 오디오 코덱 설정
format이 MP3일 경우 MP3 만 허용합니다.
audio.codecOptions No Object 오디오 코덱 상세옵션 설정 객체
codec이 MP3일 경우 codecOptions 객체는 생략합니다.
audio.codecOptions.profile No String AAC_LC, HE_AAC AAC 코덱의 profile을 설정
일반적으로 알려진 AAC_LC와 비교적 낮은 비트레이트 애플리케이션에 최적화된 HE_AAC를 제공합니다.
미 지정시 기본값으로 AAC_LC 설정
audio.channel Yes String AUTO, 1, 2 출력 오디오의 채널 설정, AUTO 설정 시 원본의 오디오 채널을 사용
참고: 인풋 미디어 파일의 오디오 채널과 다른 설정으로 인코딩 시 볼륨의 변화가 발생 할 수 있습니다.
audio.bitrate Yes String 16~320 범위의 정수, 단위: Kbps 트랜스코딩할 오디오 스트림의 비트 전송률 설정
audio.samplingRate Yes String AUTO, 11025, 22050 , 32000, 44100, 48000
단위: Hz
출력 오디오 샘플링 레이트 설정
AUTO 설정 시 원본의 오디오 샘플링 레이트를 사용
video Yes Object 트랜스코딩 비디오 옵션 설정 객체입니다.
presetType이 AUDIO 일 경우 video 객체는 생략합니다.
video.codec Yes String H264만 제공 비디오 코덱 설정
video.codecOptions Yes Object 비디오 코덱 상세옵션 설정 객체
video.codecOptions.profile Yes String BASELINE, MAIN, HIGH Video Codec Profile은 영상의 사용 용도에 맞게 H.264 코덱의 특정 기술을 사용할 수 있도록 미리 정의해 둔 표준 명세입니다.
video.codecOptions.level Yes String 1, 1b, 1.1,
1.2, 1.3,
2.1, 2.2,
3.1, 3.2,
4.1, 4.2,
5.1, 5.2
Video Codec Level은 영상을 재생하는 단말의 재생기(디코더)가 어느정도 자원을 필요로 하는지 정해놓은 표준 명세입니다.
video.codecOptions.referenceFrames No String 0~16 범위의 정수 참조 프레임 설정
비디오 압축시 참조 사용되는 프레임
미 지정시 기본값으로 3 설정
video.bitrate Yes String bitrate > 0
단위: Kbps
비디오 스트림의 비트 전송률 설정
동영상의 화질을 결정하는 매우 중요한 요소이며 1초 분량의 동영상을 구성하는 데이터의 크기를 설정
video.width Yes String AUTO, 128~4096 범위의 정수
단위: 픽셀
출력 비디오의 가로 길이
width 만 AUTO 일 경우 height 는 고정되며 width 는 본 영상의 비율에 맞춰 변환
video.height Yes String AUTO, 96~3072 범위의 정수
단위: 픽셀
출력 비디오의 세로 길이
height 만 AUTO 일 경우 width 는 고정되며 height 는 본 영상의 비율에 맞춰 변환
video.framerate Yes String AUTO, 10, 15, 23.97, 24, 29.97, 30, 50, 60 초당 프레임 수를 설정
출력 비디오 스트림에 초당 몇 개의 프레임을 보여 줄지 설정
video.keyframeInterval Yes String 1~100000 범위의 정수 키프레임 간격 설정
비디오에 키 프레임 생성되는 간격을 설정
예를들어, framerate=“30”, keyframeInterval=“2” 설정시 60 frame 마다 key frame 이 생성되며
간격이 작을수록 비디오 품질향상
video.rateControl No String ABR, CRF, CBR 비디오 변환시 비트레이트 배분 방식을 설정
CBR:고정 비트레이트로 모든 프레임에 비트레이트를 같게 변환 비트레이트가 고정되어 결과물 용량을 예측하기 쉬우나 ABR, CRF 대비 품질이 낮음
CRF:압축 효율이 좋은편이며 인코딩 전 비트레이트와 파일크기를 지정할 수 없음
ABR:가용 비트레이트로 평균 비트레이트를 유지하며 필요 비트레이트에 따라 가변적으로 변환
미 지정시 기본값으로 ABR 설정
video.resizeType No String FIT, SHRINK_TO_FIT 해상도 resize 정책을 설정
FIT: 리사이징 결과 원본 가로, 세로 중 한가지를 프리셋의 해상도에 일치하도록 변환하며 원본의 가로, 세로 모두 프리셋의 해상도보다 작은경우 upscale 함
SHRINK_TO_FIT: FIT과 동일하나 원본의 가로, 세로 모두 프리셋의 해상도보다 작은경우 upscale 하지 않음
미 지정시 기본값으로SHRINK_TO_FIT 설정

응답

필드명 타입 설명 비고
presets[] Array 생성된 Custom preset 정보
presets[].name String 생성된 Costom preset 의 이름
presets[].format String 변환된 파일의 비디오 포맷
presets[].presetType String Preset의 타입, NORMAL 혹은 AUDIO
presets[].audio Object 트랜스코딩 오디오 옵션 객체
presets[].audio.codec String 오디오 코덱
presets[].audio.codec.codecOptions Object 오디오 코덱 상세옵션 객체
presets[].audio.codec.codecOptions.profile String AAC 코덱의 profile
presets[].audio.channel String 출력 오디오의 채널
presets[].audio.bitrate String 트랜스코딩할 오디오 스트림의 비트 전송률
presets[].audio.samplingRate String 출력 오디오 샘플링 레이트
presets[].video Object 트랜스코딩 비디오 옵션 객체
presets[].video.codec String 비디오 코덱
presets[].video.codecOptions Object 비디오 코덱 상세옵션 객체
presets[].video.codecOptions.profile String H.264 코덱의 profile
presets[].video.codecOptions.level String 영상을 재생하는 단말의 재생기(디코더)가 어느 정도의 자원을 필요로 하는지 정해놓은 명세
presets[].video.codecOptions.referenceFrames String 참조 프레임
비디오 압축시 참조 사용되는 프레임
presets[].video.bitrate String 비디오 스트림의 비트 전송률
presets[].video.width String 출력 비디오의 가로 길이
presets[].video.height String 출력 비디오의 세로 길이
presets[].video.framerate String 초당 프레임 수
presets[].video.keyframeInterval String 키프레임 간격 설정
비디오에 키 프레임 생성되는 간격
presets[].video.rateControl String 비디오 변환시 비트레이트 배분 방식
presets[].video.resizeType String 해상도 resize 정책
presets[].presetId String 생성된 Custom preset의 id
presets[].presetGroup String 생성된 Custom preset의 group system, custom
presets[].type String 생성된 Custom preset의 해상도 type 프리셋 해상도가 AUTO인 경우 AUTO로 표기
presets[].costType String 생성된 Custom preset의 과금 기준 프리셋 해상도가 AUTO인 경우 AUTO로 표기되며 원본 해상도에 따라 과금
presets[].createdTime Long Custom preset 이 생성된 시간
error Object 응답 코드 및 메시지 VOD Transcoder API 오류 코드 참고
error.errorCode Integer 응답 코드(오류일 경우 오류 코드)
error.message String 응답 메시지(오류일 경우 오류 메시지)  

예시

요청 예시

POST https://vodtranscoder.apigw.ntruss.com/api/v2/presets

POST /api/v2/presets
HOST: vodtranscoder.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-apigw-api-key:AKLJsfKIy12AJDW0Q2MxANdoiAZKxWwG3NOvT6aZ
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v1:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=

{"profile":"AAC_LC"},"channel":"2","bitrate":"64","samplingRate":"44100"},"video":{"codec":"H264","codecOptions":{"profile":"BASELINE","level":"3.1","referenceFrames":"3"},"bitrate":"300","width": "320","height":"240","framerate":"30","keyframeInterval":"90","rateControl":"ABR","resizeType":"SHRINK_TO_FIT"}}'

응답 예시

HTTP/1.1 200 OK
Server: nginx
Date: Wed, 12 Sep 2018 10:18:11 GMT
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
x-ncp-trace-id: 68d1o68pm4cr63gc3169gm4p34

{"presets":[{"name":"custom240p","format":"mp4","audio":{"codec":"AAC","codecOptions":{"profile":"AAC_LC"},"channel":"2","bitrate":"64","samplingRate":"44100"},"video":{"codec":"H264","codecOptions":{"profile":"BASELINE","level":"3.1","referenceFrames":"3"},"bitrate":"300","width":"320","height":"240","framerate":"30","keyframeInterval":"90","rateControl":"ABR","resizeType":"SHRINK_TO_FIT"},"presetId":"9921da37-f391-11e8-bf37-421453cae184","presetGroup":"custom","type":"","costType":"","createdTime":1543466729}],"error":{"errorCode":0,"message":"Ok"}}

오류 코드

VOD Transcoder API 요청이 잘못되었거나, 처리 도중 오류가 발생하면 HTTP 상태코드로 성공/실패를 반환하고 JSON 형식으로 상세 메시지를 반환합니다.

오류 코드는 VOD Transcoder API의 ‘공통 오류 코드’와 ‘API Gateway 오류 코드’ 두 가지입니다.

오류 코드 응답 메시지 설명
0 Ok
240000 Form validation failed
240001 Resource not found
240002 Access denied
240003 Server error
240004 Unauthorized
240005 Bad Request Request body의 JSON 형식이 유효하지 않습니다.
240006 The request is not supported 요청 자체가 유효하지 않습니다.
240007 The input file in a format that is currently not supported by VOD Transcoder 변환할 영상의 파일 포맷이 지원되지 않습니다.
AVI, MOV, MP4, MP3 3GP, MPG, MPEG, M4V, VOB, WMV, ASF, MKV, FLV, WEBM, GIF 포맷 지원
240008 You can only cancel a job that has a status of submitted Submitted 상태인 Job 만 취소 가능합니다.
Progressing, Cancel, Fail 상태의 Job 은 취소가 불가능합니다.
240009 Deleting a system preset is not allowed System 기본 제공 Preset 은 삭제 할 수 없습니다.
240010 The request did not set content-type to “application/json” body가 포함된 요청은 Content-Type: “application/json” 헤더를 포함해 요청해야 합니다.
240011 The request did not include the required “output” object Job 생성 요청 시 output 객체가 누락되었습니다.
240012 The request did not include the required “preset id” Job 생성 요청 시 presetId가 누락되었습니다.
240013 The specified preset does not exist 요청한 preset를 찾을 수 없습니다.
240014 The request did not include the thumbnail bucket name Job 생성 요청 시 thumbnailBucketName 이 누락되었습니다.
240015 The Input file path does not start with “/” Job 생성 요청 시 inputFilePath 가 “/“로 시작하지 않습니다.
240016 The thumbnail bucket name that you specified format is not supported by VOD Transcoder Job 생성 요청 시 thumbnailBucketName 이 VOD Transcoder에서 지원하는 형식이 아닙니다.
영어, 숫자, "-", "_" 허용, 3자이상 30자 이하
240017 The job name that you specified is not allowed Job 생성 요청 시 jobName 이 VOD Transcoder에서 지원하는 형식이 아닙니다.
영어, 숫자, "-", "_" 허용, 3자이상 20자 이하
240018 The input bucket name that you specified is not allowed Job 생성 요청 시 inputBucketName 이 VOD Transcoder에서 지원하는 형식이 아닙니다.
영어, 숫자, "-", "_" 허용, 3자이상 20자 이하
240019 The output bucket name that you specified is not allowed Job 생성 요청 시 outputBucketName 이 VOD Transcoder에서 지원하는 형식이 아닙니다.
영어, 숫자, "-", "_" 허용, 3자이상 20자 이하
240020 The number of output size that you specified is not allowed by VOD Transcoder Job 생성 요청 시 outputFiles[] 크기가 올바르지 않습니다.
outputFiles 배열의 크기는 1-5
240021 The preset id that you specified is not allowed Job 생성 요청 시 presetId의 형식이 올바르지 않습니다.
240022 The output file name that you specified in the output object is not allowed Job 생성 요청 시 outputFileName 이 VOD Transcoder에서 지원하는 형식이 아닙니다.
영어, 숫자, "-", "_" 허용, 3자이상 20자 이하
240023 There are duplicated preset in a request Job 생성 요청 시 중복된 presetId가 존재합니다.
240024 A file already exists with the specified output bucket Job 생성 요청 시 outputFileName 이 이미 Object Storage bucket에 존재합니다.
240025 The access control value that you specified is not allowed : only access control [PRIVATE, PUBLIC-READ] are supported Job 생성 요청 시 accessControl 값이 올바르지 않습니다.
PRIVATE, PUBLIC-READ
240026 The thumbnail format that you specified is not allowed : only thumbnail format [PNG, JPG] are supported Job 생성 요청 시 thumbnailFileForamt 값이 올바르지 않습니다.
PNG, JPG
240027 The format of preset that you specified is not allowed : only “MP4” format is supported Custom Preset 생성 요청 시 format 값이 올바르지 않습니다.
MP4, MP3
240028 The audio codec that you specified is not allowed : only “AAC” audio codec is supported Custom Preset 생성 요청 시 audioCodec 값이 올바르지 않습니다.
AAC, MP3
240029 The profile value of audio codec that you specified is not allowed : only profile [AAC_LC, HE_AAC] are supported Custom Preset 생성 요청 시 audio.codecOptions.profile 값이 올바르지 않습니다.
AAC_LC, HE_AAC
240030 The audio channel value that you specified is not allowed : only audio channel value [AUTO, 1, 2] are supported Custom Preset 생성 요청 시 audio.channel 값이 올바르지 않습니다.
AUTO, 1, 2
240031 The audio birate value that you specified is not allowed (exceeds valid limit or wrong type) : valid value is allowed integer between 16 and 320 Custom Preset 생성 요청 시 audio.bitrate 값이 올바르지 않습니다.
16~320 범위의 정수
240032 The audio sampling rate that you specified is not allowed : only audio sampling rate value [AUTO, 11025, 22050, 32000, 44100, 48000] are supported Custom Preset 생성 요청 시 audio.samplingRate 값이 올바르지 않습니다.
AUTO, 11025, 22050 , 32000, 44100, 48000
240033 The video codec that you specified is not allowed : only “H264” format is supported Custom Preset 생성 요청 시 video.codec 값이 올바르지 않습니다.
H264 만 허용
240034 The profile of video codec that you specified is not allowed : only profile value [BASELINE, MAIN, HIGH] are supported Custom Preset 생성 요청 시 video.codecOptions.profile 값이 올바르지 않습니다.
BASELINE, MAIN, HIGH
240035 The profile leve valuel of video codec that you specified is not allowed : only profile level value [1, 1b, 1.1, 1.2, 1.3, 2.1, 2.2, 3.1, 3.2, 4.1, 4.2, 5.1, 5.2] are supported Custom Preset 생성 요청 시 video.codecOptions.level 값이 올바르지 않습니다.
1, 1b, 1.1, 1.2, 1.3, 2.1, 2.2, 3.1, 3.2, 4.1, 4.2, 5.1, 5.2
240036 The reference frames of video codec that you specified is not allowed : valid value is allowed integer between 0 and 16 Custom Preset 생성 요청 시 video.codecOptions.referenceFrames 값이 올바르지 않습니다.
0~16 범위의 정수
240037 The video bitrate value that you specified is not allowed : video bitrate value is an integer greater than 0, inclusive Custom Preset 생성 요청 시 video.bitrate 값이 올바르지 않습니다.
0 이상의 정수
240038 The width of video that you specified is not allowed : only width [AUTO, integer between 128 and 4096] are supported Custom Preset 생성 요청 시 video.width 값이 올바르지 않습니다.
AUTO, 128~4096 범위의 정수
240039 The height of video that you specified is not allowed : only width [AUTO, integer between 96 and 3072] are supported Custom Preset 생성 요청 시 video.height 값이 올바르지 않습니다.
AUTO, 96~3072 범위의 정수
240040 The frame rate of video that you specified is not allowed : only frame rate value [AUTO, 10, 15, 23.97, 24, 29.97, 30, 50, 60] are supported Custom Preset 생성 요청 시 video.framerate 값이 올바르지 않습니다.
AUTO, 10, 15, 23.97, 24, 29.97, 30, 50, 60
240041 The keyframe interval value of video that you specified is not allowed : valid value is allowed integer between 1 and 100000 Custom Preset 생성 요청 시 video.keyframeInterval 값이 올바르지 않습니다.
1~100000 범위의 정수
240042 The rate control of video that you specified is not allowed : only width [ABR, CRF, CBR] are supported Custom Preset 생성 요청 시 video.rateControl 값이 올바르지 않습니다.
ABR, CRF, CBR
240043 The resize type of video that you specified is not allowed : only resize type [FIT, SHRINK_TO_FIT] are supported Custom Preset 생성 요청 시 video.resizeType 값이 올바르지 않습니다.
FIT, SHIRINK_TO_FIT
240044 If container format is mp3, you should use MP3 audio codec MP3 Format Custom Preset 생성 요청 시, audio codec을 MP3로 설정해야 합니다.
240045 If container format is mp3, you should not use video option MP3 Format Custom Preset 생성 요청 시, video 객체(옵션) 없이 요청해야 합니다.
240046 The request did not include the required \“video\” object Custom Preset 생성 요청 시 video 객체가 누락되었습니다.
240047 The input path that you specified is not allowed InputFilePath가 올바르지 않습니다.
`특수문자 <, >, :, “,
240048 The output path that you specified is not allowed OutputFilePath가 올바르지 않습니다.
`특수문자 <, >, :, “,
240049 The thumbnail path that you specified is not allowed ThumbnailFilePath가 올바르지 않습니다.
`특수문자 <, >, :, “,