REST API

페이지 이동경로

MediaConvert API

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

API 엔드포인트 URL

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

안내
MediaConvert API는 현재 kr-central-1(카카오 & KiC) 리전만 제공합니다.

코드 예제 Media Convert API 엔드포인트 URL

https://transcoder.kr-central-1.kakaoi.io/

Method

미디어 컨버트 사용 설정

카카오 i 클라우드(이하 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

Request Header

Request 타입 필수 여부 설명
X-Auth-Token String 필수 사용자 인증 토큰

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 ▼ Structure Object Storage 버킷이 속한 프로젝트
    id String 프로젝트 ID
    name String 프로젝트 이름
    service_agent ▼ Structure 생성된 서비스 에이전트
    user ▼ Structure 유저
        id String 서비스 에이전트 ID
        trust_id String Keystone에서 발행하는 Trust의 Id

Kafka topic 구독

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

Request Syntax

코드 예제 Kafka topic 구독 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

Request Header

Request 타입 필수 여부 설명
X-Auth-Token String 필수 사용자 인증 토큰

Response Syntax

Status Code

HTTP Status 응답 내용 설명
200 Success 성공
401 Unauthorized 권한 없음 / project scope 부재 / service agent 부재
409 Conflict 이미 구독 중

이미지 정책 생성

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

  • 생성된 정책의 초기 상태는 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 타입 필수 여부 설명
source String 필수 원본 이미지 저장소

Request Header

Request 타입 필수 여부 설명
X-Auth-Token String 필수 사용자 인증 토큰
Content-Type String 필수 application/json로 고정

Request Elements

Request 타입 필수 여부 설명
target String 필수 변환 이미지 저장소
payload List 필수 버킷에 적용할 정책
- 1개 이상의 정책을 리스트 형태로 기입
- 하단의 표. TranscodeRule 참고

TranscodeRule

Name 타입 필수 여부 설명
image ▼ List 필수 버킷에 적용할 이미지 정책
    name String 필수 변환 룰 이름
- 이미지 정책 내에서 unique(유일값)해야 함
    description String 필수 변환 룰에 대한 설명
    operation String 선택 적용하고자 하는 정책 유형
- 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
size 입력값만큼 이미지를 리사이즈한 후, scale 적용
- 입력값에 따라 이미지의 너비/높이 비율이 유지되지 않을 수 있음
crop - size
- scale
- offset
이미지 scale 적용 후 offset 위치에서부터 size만큼 크롭함
crop-center - size scale 적용 후 이미지의 중심을 기준으로 size만큼 크롭함
- 너비 비율이 높을 경우 : 너비 비율에 따라 이미지 크기 조절
- 높이 비율이 높을 경우 : 높이 비율에 따라 이미지 크기 조절
crop-width - size size의 width만큼 너비를 scale한 후, size의 height만큼 높이를 크롭함

안내
최종 결과물은 ‘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 타입 필수 여부 설명
source String 필수 원본 이미지 저장소 이름
target String 필수 변환 이미지 저장소 이름
payload ▼ List 필수 버킷에 적용할 정책
- 1개 이상 입력
    image ▼ List 필수 -
        name String 필수 변환 룰 이름
        description String 필수 변환 룰 설명
        operation String 필수 적용한 정책 유형
- resize: 이미지 사이즈 조정 후 scale 적용
- crop: 이미지 scale 적용 후 자름
- crop-center: scale 적용 후 이미지의 중심을 기준으로 자름
- crop-width: 이미지 너비 scale 적용 후 높이 자름
        size []String 필수 변환된 이미지 사이즈
        scale []String 선택 원본 이미지 대비 확대 또는 축소 비율(%)
        offset []String 선택 crop 정책에 적용한 이미지 top-left position의 좌표
activated Boolean 필수 이미지 정책 상태
- false(기본값): 정책 비활성화
- true: 정책 활성화
created_at time.Time 필수 이미지 정책 생성 일자
updated_at time.Time 필수 이미지 정책 최종 수정 일자

Status Code

HTTP Status 응답 내용 설명
200 Success 성공
404 Notfound 원본/변환 이미지 저장소가 존재하지 않음
409 Rule 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 타입 필수 여부 설명
source String 필수 원본 이미지 저장소

Request Header

Request 타입 필수 여부 설명
X-Auth-Token String 필수 사용자 인증 토큰
Content-Type String 필수 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 타입 설명
source String 원본 이미지 저장소 이름
target String 변환 이미지 저장소 이름
payload ▼ List 저장된 변환 룰
    image ▼ List -
        name String 변환 룰 이름
        description String 변환 룰에 대한 설명
        operation String 적용한 정책 유형
- resize: 이미지 사이즈 조정 후 scale 적용
- crop: 이미지 scale 적용 후 자름
- crop-center: scale 적용 후 이미지의 중심을 기준으로 자름
- crop-width: 이미지 너비 scale 적용 후 높이 자름
        size []String 변환된 이미지 사이즈
        scale []String 원본 이미지 대비 확대 또는 축소 비율(%)
        offset []String crop 정책에 적용한 이미지 top-left position의 좌표
activated Boolean 이미지 정책의 활성화 상태
- false(기본값): 정책 비활성화
- true: 정책 활성화
created_at time.Time 이미지 정책 생성 시각
updated_at time.Time 이미지 정책 최종 수정 시각

Status Code

HTTP Status 응답 내용 설명
200 Success 성공
404 Notfound 해당 버킷에 등록된 정책이 존재하지 않음

이미지 정책 변경

원본 이미지 저장소에 등록된 정책을 변경합니다. 해당 버킷에 등록된 모든 정책을 삭제하고 신규 정책을 저장하는 방식입니다. 유지하고 싶은 정책이 있으면 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 타입 필수 여부 설명
source String 필수 원본 이미지 저장소

Request Header

Request 타입 필수 여부 설명
X-Auth-Token String 필수 사용자 인증 토큰
Content-Type String 필수 application/json로 고정

Request Elements

Name 타입 필수 여부 설명
target String 필수 변환 이미지 저장소
payload ▼ List 필수 저장된 변환 룰
- 버킷에 적용하고자 하는 변경된 룰
- 적어도 한 개 이상의 룰을 반드시 입력
- 해당 버킷에 등록된 룰을 삭제하고 신규 룰을 저장하므로, 유지하고자 하는 룰이 있는 경우 payload에 다시 기입해야 함
    image ▼ List 필수 버킷에 적용할 이미지 정책
        name String 필수 변환 룰 이름
- 이미지 정책 내에서 unique(유일값)해야 함
        description String 선택 변환 룰에 대한 설명
        operation String 필수 적용하고자 하는 정책 유형
- 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 타입 설명
source String 원본 이미지 저장소
target String 변환 이미지 저장소
payload ▼ List 저장된 변환 룰
    image ▼ List -
        name String 변환 룰 이름
        description String 변환 룰 설명
        operation String 적용한 정책 유형
- resize: 이미지 사이즈 조정 후 scale 적용
- crop: 이미지 scale 적용 후 자름
- crop-center: scale 적용 후 이미지의 중심을 기준으로 size만큼 crop 함
- crop-width: 이미지 너비 scale 적용 후 높이 자름
        size []String 변환된 이미지 사이즈
        scale []String 원본 이미지 대비 확대 또는 축소 비율(%)
        offset []String crop 정책에 적용한 이미지 top-left position의 좌표
activated boolean 이미지 정책 상태
- false(기본값): 정책 비활성화
- true: 정책 활성화
created_at time.Time 이미지 정책 생성 일자
updated_at time.Time 이미지 정책 최종 수정 일자

Status Code

HTTP Status 응답 내용 설명
200 Success 성공
404 Notfound 원본/변환 이미지 저장소가 존재하지 않음
404 Notfound 해당 버킷에 등록된 정책이 존재하지 않음

이미지 정책 삭제

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

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 타입 필수 여부 설명
source String 필수 원본 이미지 저장소

Request Header

Request 타입 필수 여부 설명
X-Auth-Token String 필수 사용자 인증 토큰
Content-Type String 필수 application/json로 고정

Response Syntax

Status Code

HTTP Status 응답 내용 설명
200 Success 성공
404 Notfound 해당 버킷에 등록된 정책이 존재하지 않음

이미지 정책 활성화

생성된 정책을 활성화합니다. 정책이 활성화된 시점으로부터 원본 이미지 저장소에 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 타입 필수 여부 설명
source String 필수 원본 이미지 저장소

Request Header

Request 타입 필수 여부 설명
X-Auth-Token String 필수 사용자 인증 토큰
Content-Type String 필수 application/json로 고정

Response Syntax

Status Code

HTTP Status 응답 내용 설명
200 Success 성공
404 Notfound 해당 버킷에 등록된 정책이 존재하지 않음

이미지 정책 비활성화

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

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 타입 필수 여부 설명
source String 필수 원본 이미지 저장소

Request Header

Request 타입 필수 여부 설명
X-Auth-Token String 필수 사용자 인증 토큰
Content-Type String 필수 application/json로 고정

Response Syntax

Status Code

HTTP Status 응답 내용 설명
200 Success 성공
404 Notfound 해당 버킷에 등록된 정책이 존재하지 않음