본문으로 건너뛰기

Media Convert

MediaConvert API를 사용하여 버킷에 담긴 파일을 원하는 옵션에 따라 변환하고, 이미지 처리 기능 등을 할 수 있습니다.

안내

MediaConvert API는 kr-central-1 리전만 제공합니다.

API 사용 준비

API를 호출하기 위해 필요한 사전 작업은 API 사용 준비 문서를 참고하시기 바랍니다.

API 엔드포인트 URL

API 요청을 위한 MediaConvert API 엔드포인트 URL은 다음과 같습니다.

Media Convert API 엔드포인트 URL
https://transcoder.kr-central-1.kakaoi.io/

미디어 컨버트 사용 설정

카카오클라우드(이하 KiC) 사용자는 자신이 속한 프로젝트의 Object Storage 버킷을 대상으로 미디어 컨버트 정책을 생성할 수 있습니다. 미디어 컨버트는 Object Storage와 다르게 별도의 서비스 사용 설정이 필요합니다.
미디어 컨버트는 Object Storage와 마찬가지로 API 사용을 위해 사용자 인증 토큰(API 인증 토큰, X_AUTH_TOKEN)이 필요합니다.

  • 사용자 인증 토큰 획득 방법에 대한 자세한 설명은 API 인증 토큰 발급를 참고하시기 바랍니다.
  • 미디어 컨버트는 프로젝트 단위로 작동하기 때문에, 발급받은 토큰이 project scope일 때만 사용할 수 있습니다.
  • 원본 이미지 저장소와 변환 이미지 저장소는 Object Storage 버킷의 단위로 사용합니다.

서비스 에이전트 생성

Object Storage 버킷 및 오브젝트에 접근하기 위한 서비스 에이전트를 생성합니다. 미디어 컨버트는 Object Storage 버킷에 업로드된 오브젝트를 대상으로 작동하므로 서비스 사용 전 서비스 에이전트 생성 작업이 최우선으로 진행되어야 합니다. 이 작업은 Object Storage의 엔드포인트를 통해 이루어집니다. Object Storage의 엔드포인트는 다음과 같습니다.

Object Storage 엔드포인트 URL
https://objectstorage.kr-central-1.kakaoi.io 
Request Syntax
서비스 에이전트 생성 Request Syntax
curl --location --request POST 'https://objectstorage.kr-central-1.kakaoi.io/v1_ext/project' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}"
API 호출 방식
메서드요청 URL
POST   https://objectstorage.kr-central-1.kakaoi.io/v1_ext/project
Response Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Response Syntax
서비스 에이전트 생성 Response Syntax
{
"project": {
"id": "{project-id}",
"name": "{project-name}",
"service_agent": {
"user": {
"id": "{agent-user-id}"
},
"trust_id": "{trust-id}"
}
}
}
Response Elements
Response유형설명
project ▼StructureObject Storage 버킷이 속한 프로젝트
    idString프로젝트 ID
    nameString프로젝트 이름
    service_agent ▼Structure생성된 서비스 에이전트
    user ▼Structure사용자
        idString서비스 에이전트 ID
        trust_idStringKeystone에서 발행하는 Trust의 ID

Kafka 토픽 구독

Object Storage에 오브젝트가 등록되는 정보를 담고 있는 Kafka 토픽을 구독합니다.

Request Syntax
Kafka 토픽 구독 Request Syntax
curl --location --request POST 'https://transcoder.kr-central-1.kakaoi.io/v1/project' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}"
API 호출 방식
메서드요청 URL
POST  https://transcoder.kr-central-1.kakaoi.io/v1/project
Response Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Response Syntax
Status Code
HTTP Status응답 내용설명
200Success성공
401Unauthorized권한 없음
- project scope 부재
- service agent 부재
409Conflict이미 구독 중

이미지 정책 생성

원본 이미지 저장소에 적용할 정책을 생성합니다. 리스트로 기술하여 한 번에 여러 개의 정책을 생성할 수 있습니다.

  • 생성된 정책의 초기 상태는 activated:false(비활성화)입니다.
Request Syntax
이미지 정책 생성 Request Syntax
curl --http1.1 --location --request POST 'https://transcoder.kr-central-1.kakaoi.io/v1/rules/image-source' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}" \
--header "Content-Type: application/json" \
--data-raw '{
    "target": "image-target",
    "payload": {
        "image": [{
"name": "rule_name",
"description": "rule_description",
            "operation": "resize",
            "size" : ["100x200"],
            "scale": [100],
"offset": ["0x0"]
        }]
    }
}'
API 호출 방식
메서드요청 URL
POST   https://transcoder.kr-central-1.kakaoi.io/v1/rules/{source}
Path유형필수 여부설명
sourceString필수  원본 이미지 저장소
Response Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Content-TypeString필수  application/json으로 고정
Request Elements
Request유형필수 여부설명
targetString필수  변환 이미지 저장소
payloadList필수  버킷에 적용할 정책
- 1개 이상의 정책을 리스트 형태로 기입
- TranscodeRule 참고
TranscodeRule
Name유형필수 여부설명
image ▼List필수  버킷에 적용할 이미지 정책
    nameString필수  변환 룰 이름
- 이미지 정책 내에서 유일값 이어야 함
    descriptionString필수  변환 룰에 대한 설명
    operationString선택적용하고자 하는 정책 유형
- resize: 이미지 사이즈 조정 후 scale 적용
- crop: 이미지 scale 적용 후 자름
- crop-center: scale 적용 후 이미지의 중심을 기준으로 size만큼 크롭함
- crop-width: 이미지 너비 scale 적용 후 높이 자름
- TranscodeRule 상세 참고
    size[]String선택변환 결과로 최종적으로 얻고자 하는 이미지 사이즈
- {width} x {height} 형식으로 작성하며 리스트로 기입 가능
- 최솟값: 0~1 (operation 입력값에 따라 다름), 최댓값: 858993459
- 예시: “100x100”, “100x50”
    scale[]Int필수  원본 이미지 대비 확대 또는 축소 비율(%)
- 리스트로 여러 개 기입 가능
- 100(기본값): 원본과 동일한 scale
- 입력값이 100보다 작으면 축소, 100보다 크면 확대
    offset[]String필수  정책 유형 crop 선택 시 자를 영역의 top-left position의 좌표
- {X} x {Y} 형식으로 작성하며 리스트로 기입 가능
- 미입력 시 0 x 0으로 적용
- 예시: “0x0”, “100x0”
TranscodeRule 상세
Operation 유형Option설명
resize     - size
- scale
사이즈 입력값만큼 이미지를 리사이즈한 후, 스케일 적용
- 입력값에 따라 이미지의 너비/높이 비율이 유지되지 않을 수 있음
crop- size
- scale
- offset
이미지 스케일 적용 후, 오프셋 위치에서부터 사이즈만큼 크롭함
crop-center- size스케일 적용 후 이미지의 중심을 기준으로 사이즈만큼 크롭함
- 너비 비율이 높을 경우 : 너비 비율에 따라 이미지 크기 조절
- 높이 비율이 높을 경우 : 높이 비율에 따라 이미지 크기 조절
crop-width- size사이즈의 너비(width)만큼 너비를 스케일한 후, 사이즈의 높이만큼 높이를 크롭함
안내

최종 결과물은 'size의 개수 x scale의 개수 x offset의 개수'를 기준으로 생성됩니다.

Response Syntax
이미지 정책 생성 Response Syntax
{
"source": "image-source",
"target": "image-target",
"payload": {
"image": [
{
"name": "rule_name",
"description": "rule_description",
"operation": "resize",
"size": [
"100x200"
],
"scale": [
100
],
"offset": [
"0x0"
]
}
]
},
"activated": false,
"created_at": "2021-12-28T12:26:07.647Z",
"updated_at": "2021-12-29T13:22:36.998342Z"
}
Response Elements
Response유형필수 여부설명
sourceString필수  원본 이미지 저장소 이름
targetString필수  변환 이미지 저장소 이름
payload ▼List필수  버킷에 적용할 정책
- 1개 이상 입력
    image ▼List필수  -
        nameString필수  변환 룰 이름
        descriptionString필수  변환 룰 설명
        operationString필수  적용한 정책 유형
- resize: 이미지 사이즈 조정 후 scale 적용
- crop: 이미지 scale 적용 후 자름
- crop-center: scale 적용 후 이미지의 중심을 기준으로 자름
- crop-width: 이미지 너비 scale 적용 후 높이 자름
        size[]String필수  변환된 이미지 사이즈
        scale[]String선택원본 이미지 대비 확대 또는 축소 비율(%)
        offset[]String선택Crop 정책에 적용한 이미지 top-left position의 좌표
activatedBoolean필수  이미지 정책 상태
- false(기본값): 정책 비활성화
- true: 정책 활성화
created_attime.Time필수  이미지 정책 생성 일자
updated_attime.Time필수  이미지 정책 최종 수정 일자
Status Code
HTTP Status응답 내용설명
200   Success성공
404Not found원본/변환 이미지 저장소가 존재하지 않음
409Rule already exists해당 버킷에 대한 정책이 이미 등록되어 있음

이미지 정책 조회

사용자가 지정한 원본 이미지 저장소 이름으로 등록된 이미지 정책 목록을 조회합니다.

Request Syntax
이미지 정책 목록 조회 Request Syntax
curl --http1.1 --location --request GET 'https://transcoder.kr-central-1.kakaoi.io/v1/rules/image-source' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}" \
--header "Content-Type: application/json"
API 호출 방식
메서드요청 URL
GET   https://transcoder.kr-central-1.kakaoi.io/v1/rules/{source}
Path유형필수 여부설명
sourceString필수  원본 이미지 저장소
Response Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Content-TypeString필수  application/json으로 고정
Response Syntax
이미지 정책 목록 조회 Response Syntax
{
"source": "image-source",
"target": "image-target",
"payload": {
"image": [
{
"name": "rule_name",
"description": "rule_description",
"operation": "resize",
"size": [
"100x200"
],
"scale": [
100
],
"offset": [
"0x0"
]
}
]
},
"activated": false,
"created_at": "2021-12-28T12:26:07.647Z",
"updated_at": "2021-12-29T13:22:36.998342Z"
}
Response Elements
Response유형설명
sourceString원본 이미지 저장소 이름
targetString변환 이미지 저장소 이름
payload ▼List저장된 변환 룰
    image ▼List-
        nameString변환 룰 이름
        descriptionString변환 룰에 대한 설명
        operationString적용한 정책 유형
- resize: 이미지 사이즈 조정 후 scale 적용
- crop: 이미지 scale 적용 후 자름
- crop-center: scale 적용 후 이미지의 중심을 기준으로 자름
- crop-width: 이미지 너비 scale 적용 후 높이 자름
        size[]String변환된 이미지 사이즈
        scale[]String원본 이미지 대비 확대 또는 축소 비율(%)
        offset[]Stringcrop 정책에 적용한 이미지 top-left position의 좌표
activatedBoolean이미지 정책의 활성화 상태
- false(기본값): 정책 비활성화
- true: 정책 활성화
created_attime.Time이미지 정책 생성 시각
updated_attime.Time이미지 정책 최종 수정 시각
Status Code
HTTP Status응답 내용설명
200     Success성공
404Not found해당 버킷에 등록된 정책이 존재하지 않음

이미지 정책 변경

원본 이미지 저장소에 등록된 정책을 변경합니다. 해당 버킷에 등록된 모든 정책을 삭제하고 신규 정책을 저장하는 방식입니다. 유지하고 싶은 정책이 있으면 payload에 다시 기입해야 합니다. 적어도 한 개 이상의 정책을 반드시 입력해야 합니다.

Request Syntax
이미지 정책 변경 Request Syntax
curl --http1.1 --location --request PUT 'https://transcoder.kr-central-1.kakaoi.io/v1/rules/image-source' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}" \
--header "Content-Type: application/json" \
--data-raw '{
    "target": "image-target",
    "payload": {
        "image": [{
            "name": "rule_name",
"description": "rule_description",
                "operation": "crop",
            "size" : ["100x200"],
            "offset": ["0x0"]
        },{
"name": "rule_name_2",
"description": "rule_description_2",
            "operation": "resize",
            "size" : ["100x100"],
            "scale": [30]
        }]
    
}'
API 호출 방식
메서드요청 URL
PUT   https://transcoder.kr-central-1.kakaoi.io/v1/rules/{source}
Path유형필수 여부설명
sourceString필수  원본 이미지 저장소
Response Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Content-TypeString필수  application/json으로 고정
Request Elements
Name유형필수 여부설명
targetString필수  변환 이미지 저장소
payload ▼List필수  저장된 변환 룰
- 버킷에 적용하고자 하는 변경된 룰
- 적어도 한 개 이상의 룰을 반드시 입력
- 해당 버킷에 등록된 룰을 삭제하고 신규 룰을 저장하므로, 유지하고자 하는 룰이 있는 경우 payload에 다시 기입해야 함
    image ▼List필수  버킷에 적용할 이미지 정책
        nameString필수  변환 룰 이름
- 이미지 정책 내에서 unique(유일값)해야 함
        descriptionString선택변환 룰에 대한 설명
        operationString필수  적용하고자 하는 정책 유형
- resize: 이미지 사이즈 조정 후 scale 적용
- crop: 이미지 scale 적용 후 자름
- crop-center: scale 적용 후 이미지의 중심을 기준으로 자름
- crop-width: 이미지 너비 scale 적용 후 높이 자름
- TranscodeRule 상세 참고
        size[]String필수  변환 결과 최종적으로 얻고자 하는 이미지의 사이즈
- {width} x {height} 형식으로 작성하며 리스트로 기입 가능
- 최솟값: 0~1 (operation 입력값에 따라 다름), 최댓값: 858993459
- 예시: “100x100”, “100x50”
        offset[]String선택정책 유형 crop 선택 시 자를 영역의 top-left position의 좌표
- {X} x {Y}의 형식으로 작성하며 리스트로 기입 가능
- 미입력 시 0 x 0으로 적용
- 예시: “0x0”, “100x0”
        scale[]String선택원본 이미지 대비 확대 또는 축소 비율(%)
- 리스트로 여러 개 기입 가능
- 100(기본값): 원본과 동일한 scale
- 입력값이 100보다 작으면 축소, 100보다 크면 확대
Response Syntax
이미지 정책 변경 Response Syntax
{
"source": "image-source",
"target": "image-target",
"payload": {
"image": [
{
"name": "rule_name",
"description": "rule_description",
"operation": "crop",
"size": [
"100x200"
],
"scale": [
100
],
"offset": [
"0x0"
]
},
{
"name": "rule_name_2",
"description": "rule_description_2",
"operation": "resize",
"size": [
"100x100"
],
"scale": [
30
],
"offset": [
"0x0"
]
}
]
},
"activated": false,
"created_at": "2021-12-28T12:26:07.647Z",
"updated_at": "2021-12-29T13:22:36.998342Z"
}
Response Elements
Response유형설명
sourceString원본 이미지 저장소
targetString변환 이미지 저장소
payload ▼List저장된 변환 룰
    image ▼List-
        nameString변환 룰 이름
        descriptionString변환 룰 설명
        operationString적용한 정책 유형
- resize: 이미지 사이즈 조정 후 scale 적용
- crop: 이미지 scale 적용 후 자름
- crop-center: scale 적용 후 이미지의 중심을 기준으로 size만큼 crop 함
- crop-width: 이미지 너비 scale 적용 후 높이 자름
        size[]String변환된 이미지 사이즈
        scale[]String원본 이미지 대비 확대 또는 축소 비율(%)
        offset[]Stringcrop 정책에 적용한 이미지 top-left position의 좌표
activatedboolean이미지 정책 상태
- false(기본값): 정책 비활성화
- true: 정책 활성화
created_attime.Time이미지 정책 생성 일자
updated_attime.Time이미지 정책 최종 수정 일자
Status Code
HTTP Status응답 내용설명
200     Success성공
404Not found원본/변환 이미지 저장소가 존재하지 않음
404Not found해당 버킷에 등록된 정책이 존재하지 않음

이미지 정책 삭제

원본 이미지 저장소에 등록된 모든 정책을 삭제할 수 있습니다.

Request Syntax
이미지 정책 삭제 Request Syntax
curl --http1.1 --location --request DELETE 'https://transcoder.kr-central-1.kakaoi.io/v1/rules/image-source' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}" \
--header "Content-Type: application/json"
API 호출 방식
메서드요청 URL
DELETE   https://transcoder.kr-central-1.kakaoi.io/v1/rules/{source}
Path유형필수 여부설명
sourceString필수  원본 이미지 저장소
Response Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Content-TypeString필수  application/json으로 고정
Response Syntax
Status Code
HTTP Status응답 내용설명
200    Success성공
404Not found해당 버킷에 등록된 정책이 존재하지 않음

이미지 정책 활성화

생성된 정책을 활성화합니다. 정책이 활성화된 시점으로부터 원본 이미지 저장소에 object가 업로드되면 등록된 룰에 의해 변환되어 변환 이미지 저장소에 업로드됩니다.

Request Syntax
이미지 정책 활성화 Request Syntax
curl --http1.1 --location --request GET 'https://transcoder.kr-central-1.kakaoi.io/v1/rules/image-source/activate' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}" \
--header "Content-Type: application/json"
API 호출 방식
메서드요청 URL
GET   https://transcoder.kr-central-1.kakaoi.io/v1/rules/{source}/activate
Path유형필수 여부설명
sourceString필수  원본 이미지 저장소
Response Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Content-TypeString필수  application/json으로 고정
Response Syntax
Status Code
HTTP Status응답 내용설명
200     Success성공
404Not found해당 버킷에 등록된 정책이 존재하지 않음

이미지 정책 비활성화

생성된 정책을 비활성화합니다.

Request Syntax
이미지 정책 비활성화 Request Syntax
curl --http1.1 --location --request GET 'https://transcoder.kr-central-1.kakaoi.io/v1/rules/image-source/deactivate' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}" \
--header "Content-Type: application/json"
API 호출 방식
메서드요청 URL
GET   https://transcoder.kr-central-1.kakaoi.io/v1/rules/{source}/deactivate
Path유형필수 여부설명
sourceString필수  원본 이미지 저장소
Response Header
Request유형필수 여부설명
X-Auth-TokenString필수  사용자 인증 토큰
Content-TypeString필수  application/json으로 고정
Response Syntax
Status Code
HTTP Status응답 내용설명
200     Success성공
404Not found해당 버킷에 등록된 정책이 존재하지 않음