Media Convert API

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

안내

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

API 사용 준비

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

API 엔드포인트 URL

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

Media Convert API 엔드포인트 URL

https://transcoder.kr-central-1.kakaocloud.com/

미디어 컨버트 사용 설정

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

Request Syntax

서비스 에이전트 생성 Request Syntax
curl --location --request POST 'https://objectstorage.kr-central-1.kakaocloud.com/v1_ext/project' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}"

API 호출 방식

메서드	요청 URL
POST	`https://objectstorage.kr-central-1.kakaocloud.com/v1_ext/project`

Response 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 토픽 구독

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

Request Syntax

Kafka 토픽 구독 Request Syntax
curl --location --request POST 'https://transcoder.kr-central-1.kakaocloud.com/v1/project' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}"

API 호출 방식

메서드	요청 URL
POST	`https://transcoder.kr-central-1.kakaocloud.com/v1/project`

Response Header

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

Response Syntax

상태 코드

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.kakaocloud.com/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.kakaocloud.com/v1/rules/{source}`

Path	유형	필수 여부	설명
source	String	필수	원본 이미지 저장소

Response 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	필수	변환 룰 이름 - 이미지 정책 내에서 유일값 이어야 함
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	사이즈 입력값만큼 이미지를 리사이즈한 후, 스케일 적용 - 입력값에 따라 이미지의 너비/높이 비율이 유지되지 않을 수 있음
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	유형	필수 여부	설명
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	필수	이미지 정책 최종 수정 일자

상태 코드

HTTP Status	응답 내용	설명
`200`	Success	성공
`404`	Not found	원본/변환 이미지 저장소가 존재하지 않음
`409`	Rule already exists	해당 버킷에 대한 정책이 이미 등록되어 있음

이미지 정책 조회

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

Request Syntax

이미지 정책 목록 조회 Request Syntax
curl --http1.1 --location --request GET 'https://transcoder.kr-central-1.kakaocloud.com/v1/rules/image-source' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}" \
--header "Content-Type: application/json"

API 호출 방식

메서드	요청 URL
GET	`https://transcoder.kr-central-1.kakaocloud.com/v1/rules/{source}`

Path	유형	필수 여부	설명
source	String	필수	원본 이미지 저장소

Response 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	이미지 정책 최종 수정 시각

상태 코드

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

이미지 정책 변경

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

Request Syntax

이미지 정책 변경 Request Syntax
curl --http1.1 --location --request PUT 'https://transcoder.kr-central-1.kakaocloud.com/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.kakaocloud.com/v1/rules/{source}`

Path	유형	필수 여부	설명
source	String	필수	원본 이미지 저장소

Response 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	이미지 정책 최종 수정 일자

상태 코드

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

이미지 정책 삭제

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

Request Syntax

이미지 정책 삭제 Request Syntax
curl --http1.1 --location --request DELETE 'https://transcoder.kr-central-1.kakaocloud.com/v1/rules/image-source' \
--header "X-Auth-Token: ${X_AUTH_TOKEN}" \
--header "Content-Type: application/json"

API 호출 방식

메서드	요청 URL
DELETE	`https://transcoder.kr-central-1.kakaocloud.com/v1/rules/{source}`

Path	유형	필수 여부	설명
source	String	필수	원본 이미지 저장소

Response Header

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

Response Syntax

상태 코드

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

이미지 정책 활성화

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

Request Syntax

이미지 정책 활성화 Request Syntax
curl --http1.1 --location --request GET 'https://transcoder.kr-central-1.kakaocloud.com/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.kakaocloud.com/v1/rules/{source}/activate`

Path	유형	필수 여부	설명
source	String	필수	원본 이미지 저장소

Response Header

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

Response Syntax

상태 코드

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

이미지 정책 비활성화

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

Request Syntax

이미지 정책 비활성화 Request Syntax
curl --http1.1 --location --request GET 'https://transcoder.kr-central-1.kakaocloud.com/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.kakaocloud.com/v1/rules/{source}/deactivate`

Path	유형	필수 여부	설명
source	String	필수	원본 이미지 저장소

Response Header

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

Response Syntax

상태 코드

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

API 사용 준비​

API 엔드포인트 URL​

미디어 컨버트 사용 설정​

서비스 에이전트 생성​

Request Syntax​

API 호출 방식​

Response Header​

Response Syntax​

Response Elements​

Kafka 토픽 구독​

Request Syntax​

API 호출 방식​

Response Header​

Response Syntax​

상태 코드​

이미지 정책 생성​

Request Syntax​

API 호출 방식​

Response Header​

Request Elements​

TranscodeRule​

TranscodeRule 상세​

Response Syntax​

Response Elements​

상태 코드​

이미지 정책 조회​

Request Syntax​

API 호출 방식​

Response Header​

Response Syntax​

Response Elements​

상태 코드​

이미지 정책 변경​

Request Syntax​

API 호출 방식​

Response Header​

Request Elements​

Response Syntax​

Response Elements​

상태 코드​

이미지 정책 삭제​

Request Syntax​

API 호출 방식​

Response Header​

Response Syntax​

상태 코드​

이미지 정책 활성화​

Request Syntax​

API 호출 방식​

Response Header​

Response Syntax​

상태 코드​

이미지 정책 비활성화​

Request Syntax​

API 호출 방식​

Response Header​

Response Syntax​

상태 코드​

API 사용 준비

API 엔드포인트 URL

미디어 컨버트 사용 설정

서비스 에이전트 생성

Request Syntax

API 호출 방식

Response Header

Response Syntax

Response Elements

Kafka 토픽 구독

Request Syntax

API 호출 방식

Response Header

Response Syntax

상태 코드

이미지 정책 생성

Request Syntax

API 호출 방식

Response Header

Request Elements

TranscodeRule

TranscodeRule 상세

Response Syntax

Response Elements

상태 코드

이미지 정책 조회

Request Syntax

API 호출 방식

Response Header

Response Syntax

Response Elements

상태 코드

이미지 정책 변경

Request Syntax

API 호출 방식

Response Header

Request Elements

Response Syntax

Response Elements

상태 코드

이미지 정책 삭제

Request Syntax

API 호출 방식

Response Header

Response Syntax

상태 코드

이미지 정책 활성화

Request Syntax

API 호출 방식

Response Header

Response Syntax

상태 코드

이미지 정책 비활성화

Request Syntax

API 호출 방식

Response Header

Response Syntax

상태 코드