상품 동영상 비동기 업로드 요청
톡스토어 상품 동영상 등록 시, 동영상 업로드 후, 응답된 vid 를 포함한 정보를 입력하셔야 합니다.
이를 위해 상품에 필요한 동영상을 비동기로 업로드 해주세요.
주의사항
# API를 통해 업로드된 외부 동영상은 카카오 내부 플랫폼을 통해 인코딩 되어 서비스됩니다.
# 형식에 맞지 않는 동영상 파일 url의 경우 인코딩에 실패할 수 있습니다.
- 동영상 권장 해상도: 대표 이미지와 동일한 비율 권장 (1:1 or 3:4)
- 권장 사이즈 : 750x750 or 750x1000 (pixel)
- 권장 동영상 길이: 1분 미만
- 지원 파일 및 형식 : 500MB 이하의 MP4, MOV, MKV, AVI, WMV, WEBM, TS 등
# UTF-8 방식을 사용해서 인코딩된 URL만 허용합니다.
POST /v2/store/products/videos/upload
요청
| 키 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| url | String | 필수 | 접근 가능한 동영상의 url |
<응답 샘플>
상품 동영상
POST /v2/store/products/videos/upload?
응답
성공시에는 카카오 동영상 id 가 응답에 포함됩니다.
vid 를 파라미터로 전달해 인코딩 진행 상태나, 동영상의 메타 정보를 조회할 수 있습니다.
| 키 | 타입 | 설명 |
|---|---|---|
| vid | String | 업로드된 파일의 id |
<응답 샘플>
상품 동영상
{
"vid": "rvfmt81n1cp3d46f123456789"
}
상품 동영상 인코딩 진행률 조회
상품 동영상 비동기 업로드 요청의 인코딩 진행 정도를 조회합니다.
영상의 크기가 클수록 인코딩 시간이 오래 소요될 수 있습니다.
GET /v2/store/products/videos/progress
요청
| 키 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| vid | String | 필수 | 업로드된 동영상 id |
응답
| 필드명 | 타입 | 설명 |
|---|---|---|
| progress | Number | 업로드된 동영상의 인코딩 진행률(0 ~ 100) |
<응답 샘플>
상품 동영상
{
"progress": 33
}
상품 동영상 업로드 정보 조회
API를 통해 업로드된 동영상의 정보를 조회합니다.
주의사항
동영상 재생 url 은 60분 동안만 유효합니다.
GET /v2/store/products/videos/meta
요청
| 키 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| url | String | 필수 | 접근 가능한 동영상의 url |
응답
| 필드명 | 타입 | 설명 |
|---|---|---|
| vid | String | 동영상 id |
| status | String | 동영상 상태 SERVICE: 인코딩 완료. 상품 등록 가능한 상태 ENCODING: 인코딩 중 ILLEGAL,VIOLATION,DELETED: 검수 과정에서 불법 촬영 등의 이유로 삭제되거나 차단된 경우 ERROR: 동영상 인코딩을 정상적으로 처리할 수 없는 경우 |
| thumbnail | String | 대표 썸네일 주소 |
| thumbnailIndex | Integer | 대표 썸네일 번호 (범위: 0 ~ 4) |
| thumbnailList | Array<String> | 썸네일 후보 목록 |
| width | Integer | 동영상 가로 길이 |
| height | Integer | 동영상 세로 길이 |
| playUrls | Array<String> | 동영상 재생 주소 목록 |
<응답 샘플>
상품 동영상
{
"vid": "rvfmt81n1cp3d46f123456789",
"status": "SERVICE",
"thumbnail": "https://thumb.kakaocdn.net/dna/kamp/source/~/thumbs/1.jpg?credential=00&expires=00&kamp_tidx=0&signature=00%3D&ts=1755822535",
"thumbnailIndex": 0,
"thumbnailList": [
"https://thumb.kakaocdn.net/dna/kamp/source/~/thumbs/1.jpg?credential=00&expires=00&kamp_tidx=0&signature=00%3D&ts=1755822535",
"https://thumb.kakaocdn.net/dna/kamp/source/~/thumbs/2.jpg?credential=00&expires=00&kamp_tidx=0&signature=00%3D&ts=1755822535",
"https://thumb.kakaocdn.net/dna/kamp/source/~/thumbs/3.jpg?credential=00&expires=00&kamp_tidx=0&signature=00%3D&ts=1755822535",
"https://thumb.kakaocdn.net/dna/kamp/source/~/thumbs/4.jpg?credential=00&expires=00&kamp_tidx=0&signature=00%3D&ts=1755822535",
"https://thumb.kakaocdn.net/dna/kamp/source/~/thumbs/5.jpg?credential=00&expires=00&kamp_tidx=0&signature=00%3D&ts=1755822535"
],
"width": 1920,
"height": 1080,
"playUrls": [
"https://vsak1.play.kakao.com/vod/~/hls/vhs/plain/adaptive.m3u8?px-time=1758556566&px-bps=1440230&px-bufahead=97&px-hash=6e7d1ebcfda3102cce686116fc1c755d",
"https://vsak1.play.kakao.com/vod/~/mp4/mp4/mp4_720P_2M_T1.mp4?px-time=1758556566&px-bps=1440230&px-bufahead=97&px-hash=6e7d1ebcfda3102cce686116fc1c755d",
"https://vsak1.play.kakao.com/vod/~/mp4/mp4/mp4_360P_500K_T1.mp4?px-time=1758556566&px-bps=1440230&px-bufahead=97&px-hash=6e7d1ebcfda3102cce686116fc1c755d"
]
}상품 동영상 썸네일 변경
동영상의 썸네일을 변경합니다.
상품 동영상 업로드 정보 조회 API 에서 조회된 thumbnailList 필드의 index 를 입력 합니다.
PUT /v2/store/products/videos/thumbnail/representative
요청
| 키 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| vid | STRING | 필수 | 업로드된 동영상 id |
| index | INTEGER | 필수 | 썸네일 목록의 인덱스(0 ~ 4) |
응답 샘플
200 ok