Job 생성

VOD Transcoder는 Job을 생성하기 위한 API를 제공하며, 생성한 Job의 확인을 위해 Job 목록 조회 APIJob 정보 조회 API를 제공합니다.


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

요청

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

요청 헤더

헤더명 설명
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 요청 시 필드명의 대소문자 구분이 필요합니다.

필드명 필수 여부 타입 제약 사항 설명
jobName Yes String 영문, 숫자, “-”, “_” 허용 최소 3자 최대 20자까지 입력 생성할 Job 이름
notificationUrl No String Notification URL 참고 Notification을 callback 받을 URL
inputs[] Yes Array 변환할 영상 옵션 설정 배열
inputs[].inputBucketName Yes String 영문, 숫자, “-”, “_” 허용 최소 3자 최대 30자까지 입력 변환할 영상이 저장되어 있는
Object Storage Bucket 명
inputs[].inputFilePath Yes String ”/“, 확장자명(*.mp4) 포함, 특수문자`<, >, :, “, , ?, *, % //입력 불가, 1024자 이하<br />AVI, MOV, MP4, 3GP, MPG, MPEG, M4V, VOB, WMV, ASF, MKV, FLV, WEBM, MP3, GIF 포맷 지원`
output Yes Object 출력물에 필요한 파라미터
output.outputBucketName Yes String 영문, 숫자, “-”, “_” 허용 최소 3자 최대 30자까지 입력 비디오 출력물을 저장할 Object Storage Bucket 명
output.outputFilePath Yes String ”/“로 시작, 특수문자`<, >, :, “, , ?, *, % //`입력 불가, outputFileName 포함1024자 이하
output.thumbnailOn Yes String true, false 썸네일 이미지 생성 여부
output.thumbnailBucketName Conditional String 영문, 숫자, “-”, “_” 허용 최소 3자 최대 30자까지 입력
thumbnailOn: true 설정 시 필수 입력
썸네일 이미지를 저장할 Object Storage Storage 명
output.thumbnailFilePath Conditional String ”/“로 시작, 특수문자`<, >, :, “, , ?, *, % //입력 불가, outputFileName 포함 1024자 이하<br />thumbnailOn: true` 설정 시 필수 입력
output.thumbnailFileFormat No String PNG, JPG 썸네일 이미지의 포맷을 지정
미 지정시 기본값으로 PNG가 설정
output.thumbnailAccessControl No String PRIVATE, PUBLIC-READ 썸네일 이미지 파일의 Object Storage 공개 범위를 지정
미 지정시 기본값으로 PRIVATE 설정
output.outputFiles[] Yes Array 1개 인풋에 대해 최대 5개의 프리셋으로 변환 가능 output file 설정에 필요한 배열
output.outputFiles[].presetId Yes String 영문, 숫자, “-” 허용 변환할 영상의 프리셋 ID
output.outputFiles[].outputFileName Yes String 영문, 숫자, “-”, “_” 허용 최소 3자 이상 20자 이하 입력
공백 허용 안 함
출력된 파일명
output.outputFiles[].accessControl No String PRIVATE, PUBLIC-READ 출력된 비디오 파일의 Object Storage 공개 범위를 지정
미 지정시 기본값으로 PRIVATE 설정

응답

필드명 타입 설명 비고
jobs[] Array 생성된 JobId 목록
jobs[].jobId String 생성된 JobId
error Object 오류 응답 코드 및 메시지 VOD Transcoder API 오류 코드 참고
error.errorCode Integer 응답 코드(오류일 경우 오류 코드)
error.message String 응답 메시지(오류일 경우 오류 메시지)

Notification URL

Job 생성 시 Notification URL을 등록해두면 Job 상태 변경(Progressing, Success, Failed)에 대한 콜백을 받을 수 있습니다.

선택 옵션이므로 반드시 설정할 필요는 없으며, 이벤트가 발생하면 아래와 같은 형태로 callback 이 발송됩니다. (HTTP POST로 발송)

{
   "jobId" : "JOB_ID",
   "status" : "FAILED|PROGRESSING|SUCCESS"
}

예시

요청 예시

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

POST /api/v2/jobs
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=

{"jobName": "api-guide", "inputs": [{ "inputBucketName": "api-guide","inputFilePath": "/Sample.mp4"}],"output":{"outputBucketName": "api-guide","outputFilePath": "/vodtr/","thumbnailOn":"true","thumbnailBucketName": "api-guide","thumbnailFilePath":"/vodtr/","outputFiles": [{"presetId": "0dfd1eee-04c9-11e8-b51d-421453cae184","outputFileName": "720p"}]}}

응답 예시

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

{"jobs":[{"jobId":"ohkivb8pbqxxo5z8kayhn8pqnpnzmkbz"}],"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가 올바르지 않습니다.
`특수문자 <, >, :, “,