Media Convert API
Media Convert API를 사용하여 버킷에 담긴 파일을 원하는 옵션에 따라 변환하고, 이미지 처리 기능 등을 할 수 있습니다.
Media Convert API는 kr-central-1
리전만 제공합니다.
API 사용 준비
API를 호출하기 위해 필요한 사전 작업은 API 사용 준비 문서를 참고하시기 바랍니다.
API 엔드포인트 URL
API 요청을 위한 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의 엔드포인트는 다음과 같습니다.
https://objectstorage.kr-central-1.kakaocloud.com
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
{
"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
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
Status Code
HTTP Status | 응답 내용 | 설명 |
---|---|---|
200 | Success | 성공 |
401 | Unauthorized | 권한 없음 - project scope 부재 - service agent 부재 |
409 | Conflict | 이미 구독 중 |
이미지 정책 생성
원본 이미지 저장소에 적용할 정책을 생성합니다. 리스트로 기술하여 한 번에 여러 개의 정책을 생성할 수 있습니다.
- 생성된 정책의 초기 상태는
activated:false
(비활성화)입니다.
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
{
"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 | Not found | 원본/변환 이미지 저장소가 존재하지 않음 |
409 | Rule already exists | 해당 버킷에 대한 정책이 이미 등록되어 있음 |
이미지 정책 조회
사용자가 지정한 원본 이미지 저장소 이름으로 등록된 이미지 정책 목록을 조회합니다.
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
{
"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 | 이미지 정책 최종 수정 시각 |