이 문서는 디스플레이 소재 API 사용 방법을 안내합니다.
2023년 8월 30일 업데이트로 아래 디스플레이 소재 유형이 추가되었습니다.
캠페인 유형 | 소재 유형 | 홍보 이미지 | 프로필 이미지 |
---|---|---|---|
디스플레이 | 이미지 네이티브(IMAGE_NATIVE) | 720x1280 이상 (9:16), 500KB, JPG/JPEG/PNG | 300x300 이상 (1:1), 500KB, JPG/JPEG/PNG |
2023년 2월 21일 업데이트로 캠페인 유형별 생성 가능한 소재 유형이 아래와 같이 변경되었습니다.
캠페인 유형 | 소재 유형 | 홍보 이미지 | 프로필 이미지 |
---|---|---|---|
카카오 비즈보드 | 이미지 배너(IMAGE_BANNER) | 1029x258, 300KB, PNG-24 | |
디스플레이 | 이미지 네이티브(IMAGE_NATIVE) | 500x500 이상 (1:1), 500KB, JPG/JPEG/PNG 1200x600 이상 (2:1), 500KB, JPG/JPEG/PNG |
300x300 이상 (1:1), 500KB, JPG/JPEG/PNG |
기존에 제공되던 URL과 더불어 다양한 유형의 소재 랜딩 유형 및 랜딩 설정이 가능합니다. 카카오 비즈보드 유형의 캠페인 하위에만 설정 가능하며, 랜딩 설정을 위한 목록 조회 API는 신규로 제공하지만 애드뷰 생성, 비즈니스폼등의 생성 API는 제공하지 않습니다. 카카오페이 구매의 경우 생성 및 수정은 불가능하며 조회만 가능합니다.
자세한 사용 방법은 아래 표를 참고합니다.
유형 | 파라미터 |
---|---|
URL | mobileLandingUrl 에 설정 |
챗봇, 채널웹뷰 | 카카오톡 채널 프로필 목록 보기 API 사용 |
애드뷰 | 애드뷰 목록 보기 API 사용 |
비즈니스폼 | 비즈니스폼 목록 보기 API 사용 |
톡캘린더 | 이벤트 ID 사용 |
채널포스트 | 채널포스트 ID 사용 |
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/creatives |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
디스플레이 소재를 생성합니다. 소재 생성 요청은 소재 유형(format)을 반드시 이미지 배너(IMAGE_BANNER), 이미지 네이티브(IMAGE_NATIVE) 중 하나로 명시해야 합니다. 소재 유형에 따라 전달해야 하는 파라미터 종류가 다릅니다. 예를 들어 이미지 배너는 imageFileUrl
을, 이미지 네이티브는 imageFileUrl
과 profileImageFileUrl
을 각각 전달합니다.
소재 생성하기 API는 이미지 등록을 위해 application/json
과 multipart/form-data
두 가지 Content-Type
을 지원합니다. 어느 방식으로 요청하더라도 소재 생성 결과는 같습니다.
imageFileUrl
파라미터로 http://
또는 https://
URL 형식의 소재 이미지 경로 전달imageFile
파라미터로 로컬 파일 경로 전달액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 POST
로 요청하며, 요청이 성공하면 응답 본문에 JSON
객체로 생성된 소재의 상세 정보를 목록으로 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
비즈보드 X 도달, 다음쇼핑 유형의 캠페인 하위에는 소재 생성이 불가능합니다.
이 API는 사용자 계정, 광고계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
adGroupId | Long |
광고그룹 번호 | O |
format | String |
소재 유형 IMAGE_BANNER (고정값) |
O |
imageFileUrl | String |
홍보이미지 사이즈, 용량, 파일형식 1029x258, 300KB, PNG-24 http:// 또는 https:// 형식의 URL형태로 요청 |
application/json 방식일 경우 필수 |
imageFile | Multipart File |
홍보이미지 사이즈, 용량, 파일형식 1029x258, 300KB, PNG-24 로컬 파일 경로 입력 |
multipart/form-data 방식일 경우 필수 |
landingInfo | LandingInfo |
랜딩 유형 카카오 비즈보드 유형의 캠페인 하위 소재만 설정 가능 |
X |
pcLandingUrl | String |
랜딩 URL PC용 URL로 http:// 또는 https:// 유효한 형식 입력 카카오 비즈보드 유형의 캠페인에는 설정할 수 없습니다. |
X |
mobileLandingUrl | String |
랜딩 URL 모바일용 URL로 http:// 또는 https:// 형식의 유효한 형식 입력 |
X |
rspvLandingUrl | String |
랜딩 URL 반응형 URL로 http:// 또는 https:// 형식의 유효한 형식 입력 카카오 비즈보드 유형의 캠페인에는 설정할 수 없습니다. |
X |
altText | String |
소재 설명 최대 30자 장애인에게 음성 안내되는 내용으로 특수문자는 사용 불가능 |
O |
name | String |
소재 이름 최대 40자 설정하지 않은 경우 {캠페인 유형}_{캠페인 목표}_{현재시간}_{소재 사이즈} 로 생성 |
X |
opinion | String |
의견(최대: 1,000자) | X |
opinionProofFileUrlList | String[] |
증빙application/json 방식 요청 시 사용 가능http:// 또는 https:// 형식의 증빙 파일 정보JPG/JPEG/PNG/PDF 형식 지원 최대 10개, 전체 파일 합계 용량 10MB 이하 |
X |
opinionProofFileList | Multipart File[] |
증빙multipart/form-data 방식 요청 시 사용 가능JPG/JPEG/PNG/PDF 형식 지원 최대 10개, 전체 파일 합계 용량 10MB 이하 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
adGroupId | Long |
광고그룹 번호 | O |
format | String |
소재 유형 IMAGE_NATIVE (고정값) |
O |
profileImageFileUrl | String |
프로필이미지 사이즈, 용량, 파일형식 300x300 이상 (1:1), 500KB, JPG/JPEG/PNG http:// 또는 https:// 형식의 유효한 형식 입력 |
application/json 방식일 경우 필수 |
profileImageFile | Multipart File |
프로필이미지 사이즈, 용량, 파일형식 300x300 이상 (1:1), 500KB, JPG/JPEG/PNG 로컬 파일 경로 입력 |
multipart/form-data 방식일 경우 필수 |
imageFileUrl | String |
홍보이미지 사이즈, 용량, 파일형식 500x500 이상 (1:1), 500KB, JPG/JPEG/PNG 1200x600 이상 (2:1), 500KB, JPG/JPEG/PNG 720x1280 이상 (9:16), 500KB, JPG/JPEG/PNG http:// 또는 https:// 형식의 유효한 형식 입력 |
application/json 방식일 경우 필수 |
imageFile | Multipart File |
홍보이미지 사이즈, 용량, 파일형식 500x500 이상 (1:1), 500KB, JPG/JPEG/PNG 1200x600 이상 (2:1), 500KB, JPG/JPEG/PNG 720x1280 이상 (9:16), 500KB, JPG/JPEG/PNG 로컬 파일 경로 입력 |
multipart/form-data 방식일 경우 필수 |
title | String |
타이틀 최대 25자 |
O |
profileName | String |
프로필 이름 최대 20자 |
O |
description | String |
홍보문구 최대 45자 |
O |
actionButton | ActionButton | 행동유도버튼 | O |
pcLandingUrl | String |
PC 랜딩 URL PC용 URL로 http:// 또는 https:// 유효한 형식 입력 카카오 비즈보드 유형의 캠페인에는 설정할 수 없습니다. |
X |
mobileLandingUrl | String |
모바일 랜딩 URL 모바일용 URL로 http:// 또는 https:// 유효한 형식 입력 |
X |
rspvLandingUrl | String |
반응형 랜딩 URL 반응형 URL로 http:// 또는 https:// 유효한 형식 입력 카카오 비즈보드 유형의 캠페인에는 설정할 수 없습니다. |
X |
altText | String |
소재 설명 최대 30자 장애인에게 음성 안내되는 내용으로 특수문자는 사용 불가능 |
O |
name | String |
소재 이름 최대 40자 설정하지 않은 경우 {캠페인 유형}_{캠페인 목표}_{현재시간}_{소재 사이즈} 로 생성 |
X |
opinion | String |
의견(최대: 1,000자) | X |
opinionProofFileUrlList | String[] |
증빙application/json 방식 요청 시 사용 가능http:// 또는 https:// 형식의 증빙 파일 정보JPG/JPEG/PNG/PDF 형식 지원 최대 10개, 전체 파일 합계 용량 10MB 이하 |
X |
opinionProofFileList | Multipart File[] |
증빙multipart/form-data 방식 요청 시 사용 가능JPG/JPEG/PNG/PDF 형식 지원 최대 10개, 전체 파일 합계 용량 10MB 이하 |
X |
이름 | 타입 | 설명 |
---|---|---|
landingType | LandingType |
랜딩 유형 |
profileId | String |
PF_BOT (챗봇), CHANNEL_WEBVIEW (채널웹뷰) 랜딩 사용시 카카오톡 채널 프로필 ID 카카오톡 채널 프로필 보기 API를 통해 조회되는 응답 중 카카오톡 채널 프로필 ID를 요청 참고: 카카오톡 채널 프로필 ID 확인 방법 |
action | String |
PF_BOT (챗봇) 랜딩 사용시 키워드 |
adViewItem | AdViewItem |
AD_VIEW (애드뷰) 랜딩 사용시 애드뷰 객체 연동 가능한 애드뷰 랜딩 유형 목록 보기 API를 통해 조회되는 id를 사용 |
url | String |
CHANNEL_WEBVIEW (채널웹뷰) 랜딩 사용시 URL |
bizFormId | Long |
BIZ_FORM (비즈니스폼) 랜딩 사용시 비즈니스폼 번호 연동 가능한 비즈니스폼 랜딩 유형 목록 보기 API를 통해 조회되는 bizFormId를 사용 |
talkCalendarEventId | String |
TALK_CALENDAR (톡캘린더) 랜딩 사용시 톡캘린더 아이디 영문과 숫자만 허용되며, 한글, 공백, 특수문자는 사용불가능 |
channelPostId | Long |
CHANNEL_POST (채널포스트) 랜딩 사용시 채널 포스트 아이디 연동 가능한 채널포스트 랜딩 유형 목록 보기 API를 통해 조회되는 포스트번호를 사용 |
이름 | 설명 |
---|---|
PF_BOT | 챗봇 |
AD_VIEW | 애드뷰 |
CHANNEL_WEBVIEW | 채널웹뷰 |
BIZ_FORM | 비즈니스폼 |
TALK_CALENDAR | 톡캘린더 |
CHANNEL_POST | 채널포스트 |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
애드뷰 번호 |
랜딩 URL은 세 종류입니다.
PC용 URL(pcLandingUrl), 모바일용 URL(mobileLandingUrl), 반응형 URL(rspvLandingUrl) 으로 이루어진 랜딩 URL은 개별적으로는 필수(Required)가 아니지만 최소 1개 이상의 랜딩 URL을 필수로 설정해야 합니다.
디스플레이 광고 소재 중 비디오 네이티브와 이미지 박스는 종류별 랜딩 URL을 제공하지 않습니다.
이름 | 타입 | 설명 |
---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
creativeId | Long |
소재 번호 소재 수정사항 심사 중, 수정사항 심사 보류 상태일 경우 임시로 발급된 신규 소재 번호 그 외 심사 상태에서는 원본 소재 번호와 동일함 |
adGroupId | Long |
광고그룹 번호 |
format | String |
소재 유형 IMAGE_BANNER |
image | Image |
업로드 된 홍보 이미지 |
landingInfo | LandingInfo |
랜딩 정보 |
pcLandingUrl | String |
랜딩 URL (PC용 URL) |
mobileLandingUrl | String |
랜딩 URL (모바일용 URL) |
rspvLandingUrl | String |
랜딩 URL (반응형 URL) |
altText | String |
소재 설명 |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
systemConfig | String |
소재 시스템 상태 ON, ADMIN_STOP 중 하나 |
name | String |
소재 이름 |
reviewStatus | String |
심사 상태 APPROVED(승인), WAITING(심사중), REJECTED(심사보류), MONITORING_REJECTED(관리자정지) 중 하나 |
statusDescription | String |
소재의 게재와 관련된 현재 상태 |
opinionProof | OpinionFile[] |
심사 처리를 위한 의견, 증빙자료 파일 목록 |
createdDate | String |
소재 생성일시 |
lastModifiedDate | String |
소재 마지막 수정일시 |
rejectedReason | Array |
소재 심사 사유 (비어있는 배열) |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
creativeId | Long |
소재 번호 소재 수정사항 심사 중, 수정사항 심사 보류 상태일 경우 임시로 발급된 신규 소재 번호 그 외 심사 상태에서는 원본 소재 번호와 동일함 |
adGroupId | Long |
광고그룹 번호 |
format | String |
소재 유형 IMAGE_NATIVE |
profileImage | Image |
업로드 된 프로필 이미지 |
image | Image |
업로드 된 홍보 이미지 |
title | String |
타이틀 |
profileName | String |
프로필 이름 |
description | String |
홍보문구 |
actionButton | String |
행동유도버튼 |
pcLandingUrl | String |
랜딩 URL (PC용 URL) |
mobileLandingUrl | String |
랜딩 URL (모바일용 URL) |
rspvLandingUrl | String |
랜딩 URL (반응형 URL) |
altText | String |
소재 설명 |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
systemConfig | String |
소재 시스템 상태 ON, ADMIN_STOP 중 하나 |
name | String |
소재 이름 |
reviewStatus | String |
심사 상태 APPROVED(승인), WAITING(심사중), REJECTED(심사보류), MONITORING_REJECTED(관리자정지) 중 하나 |
statusDescription | String |
소재의 게재와 관련된 현재 상태 |
opinionProof | OpinionFile[] |
심사 처리를 위한 의견, 증빙자료 파일 목록 |
createdDate | String |
소재 생성일시 |
lastModifiedDate | String |
소재 마지막 수정일시 |
rejectedReason | Array |
소재 심사 사유 (비어있는 배열) |
curl -X POST "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
-H "Content-Type: application/json" \
-d '{
"adGroupId":1234,
"format":"IMAGE_BANNER",
"imageFileUrl":"https://www.image.com/sample.png",
"altText":"소재설명",
"landingInfo": {
"landingType":"AD_VIEW",
"adViewItem":{"id":1}
},
"name": "첫번째_이미지배너"
}'
curl -X POST "http://api.moment.kakao.com/v4/creatives" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
\"adGroupId\":5678,
\"format\":\"IMAGE_NATIVE\",
\"profileImageFileUrl\":\"http://www.company.com/images/sample_image_native.jpg\",
\"imageFileUrl\":\"http://www.company.com/images/sample_image_banner.jpg\",
\"altText\":\"소재설명\",
\"title\":\"타이틀\",
\"profileName\":\"프로필이름\",
\"description\":\"홍보문구\",
\"actionButton\":\"JOIN\",
\"mobileLandingUrl\":\"http://www.daum.net\",
\"name\":\"네이티브_소재_등록\"
}'
curl -X POST "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: multipart/form-data" \
-F "adGroupId=1234" \
-F "format=IMAGE_BANNER" \
-F "imageFile=@로컬_640X200_이미지_경로" \
-F "altText=소재설명" \
-F "name=첫번째_이미지배너" \
-F "mobileLandingUrl=http://www.daum.net" \
-F "landingInfo.landingType=AD_VIEW" \
-F "landingInfo.adViewItem.id=쿼리검색어"
curl -X POST "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: multipart/form-data" \
-F "adGroupId=17181" \
-F "format=IMAGE_NATIVE" \
-F "profileImageFile=@로컬_300X300_이미지_경로" \
-F "imageFile=@로컬_640X480_이미지_경로" \
-F "altText=소재설명" \
-F "title=타이틀" \
-F "profileName=프로필이름" \
-F "description=홍보문구" \
-F "actionButton=JOIN" \
-F "mobileLandingUrl=http://www.daum.net"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1,
"creativeId": 2,
"adGroupId": 1234,
"format": "IMAGE_BANNER",
"name": "첫번째_이미지배너",
"landingInfo": {
"landingType": "AD_VIEW",
"adViewItem": {"id":1}
},
"pcLandingUrl": null,
"mobileLandingUrl": "http://www.daum.net",
"rspvLandingUrl": null,
"frequencyCap": null,
"frequencyCapType": "AUTO",
"config": "ON",
"systemConfig": "ON",
"reviewStatus": "WAITING",
"image": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_xxx.jpeg",
"fileName": "sample.jpeg",
"width": 640,
"height": 100,
"size": 50000
},
"altText": "소재설명",
"statusDescription": "심사중",
"createdDate": "2020-01-01T00:00:00.00000",
"lastModifiedDate": "2020-01-01T00:00:00.000000",
"rejectedReason": []
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1234,
"creativeId": 1235
"adGroupId": 5678,
"format": "IMAGE_NATIVE",
"name": "모먼트_소재_등록",
"pcLandingUrl": null,
"mobileLandingUrl": "http://www.daum.net",
"rspvLandingUrl": null,
"frequencyCap": null,
"frequencyCapType": "AUTO",
"config": "ON",
"systemConfig": "ON",
"reviewStatus": "WAITING",
"image": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_xxx.jpg",
"fileName": "sample_image_banner.jpg",
"width": 640,
"height": 480,
"size": 100000
},
"title": "타이틀",
"actionButton": "JOIN",
"profileName": "프로필이름",
"profileImage": {
"url": "http://xxx.kakao.co.kr/sample_image_native_xxx.jpg",
"fileName": "sample_image_native.jpeg",
"width": 300,
"height": 300,
"size": 50000
},
"altText": "소재설명",
"description": "홍보문구",
"statusDescription": "심사중",
"createdDate": "2020-01-01T00:00:00.000000",
"lastModifiedDate": "2020-01-01T00:00:00.000000",
"rejectedReason": []
}
메서드 | URL | 인증 방식 |
---|---|---|
PUT |
https://apis.moment.kakao.com/openapi/v4/creatives |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
디스플레이 소재를 수정합니다. 소재 유형에 따라 전달해야 하는 파라미터 종류가 다릅니다. 예를 들어 이미지 배너(IMAGE_BANNER)는 imageFileUrl
을, 이미지 네이티브(IMAGE_NATIVE)는 imageFileUrl
과 profileImageFileUrl
을 각각 전달합니다.
소재 수정 API는 이미지 등록을 위해 application/json
과 multipart/form-data
두 가지 Content-Type
을 지원합니다. application/json
방식으로 호출할 때는 imageFileUrl
파라미터로 http://
또는 https://
URL 형식으로 소재 이미지를 전달해야 합니다. multipart/form-data
방식으로 호출할 때는 imageFile
파라미터에 경로를 지정해 로컬에 저장된 파일을 전달할 수 있습니다. 어느 방식으로 요청하더라도 소재 수정 결과는 같습니다.
imageFileUrl
또는 profileImageFileUrl
이 요청 Body
에 없으면 기존에 등록된 이미지를 활용합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 PUT
으로 요청하며, 성공 시 응답 본문에 JSON
객체로 소재 상세 정보를 목록으로 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
비즈보드 X 도달, 다음쇼핑 유형의 캠페인 하위에는 소재 수정이 불가능합니다.
이 API는 사용자 계정, 광고계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
O |
adGroupId | Long |
광고그룹 번호 | O |
format | String |
소재 유형 IMAGE_BANNER (고정값) |
O |
imageFileUrl | String |
홍보이미지 사이즈, 용량, 파일형식 1029x258, 300KB, PNG-24 http:// 또는 https:// 형식의 URL형태로 요청 |
X application/json 방식일 경우 사용 가능 |
imageFile | Multipart File |
홍보이미지 사이즈, 용량, 파일형식 1029x258, 300KB, PNG-24 로컬 파일 경로 입력 |
X multipart/form-data 방식일 경우 사용 가능 |
landingInfo | LandingInfo |
랜딩 정보 랜딩 URL 3가지 유형과 동시에 요청 불가능 |
X |
pcLandingUrl | String |
PC 랜딩 URL PC용 URL로 http:// 또는 https:// 유효한 형식 입력 카카오 비즈보드 유형의 캠페인에는 설정할 수 없으며 landingInfo와 동시에 요청 불가 |
X |
mobileLandingUrl | String |
모바일 랜딩 URL 모바일용 URL로 http:// 또는 https:// 유효한 형식 입력 landingInfo와 동시에 요청 불가 |
X |
rspvLandingUrl | String |
반응형 랜딩 URL 반응형 URL로 http:// 또는 https:// 유효한 형식 입력 카카오 비즈보드 유형의 캠페인에는 설정할 수 없으며 landingInfo와 동시에 요청 불가 |
X |
altText | String |
소재 설명 최대 30자 장애인에게 음성 안내되는 내용으로 특수문자는 사용 불가능 |
O |
name | String |
소재 이름 최대 40자 요청 시 포함되지 않으면 생성 시의 이름으로 대체 |
X |
opinion | String |
의견(최대: 1,000자) | X |
opinionProofFileUrlList | String[] |
증빙application/json 방식 요청 시 사용 가능http:// 또는 https:// 형식의 증빙 파일 정보JPG/JPEG/PNG/PDF 형식 지원 최대 10개, 전체 파일 합계 용량 10MB 이하 |
X |
opinionProofFileList | Multipart File[] |
증빙multipart/form-data 방식 요청 시 사용 가능JPG/JPEG/PNG/PDF 형식 지원 최대 10개, 전체 파일 합계 용량 10MB 이하 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
O |
adGroupId | Long |
광고그룹 번호 | O |
format | String |
소재 유형 IMAGE_NATIVE (고정값) |
O |
profileImageFileUrl | String |
프로필이미지 사이즈, 용량, 파일형식 300x300 이상 (1:1), 500KB, JPG/JPEG/PNG http:// 또는 https:// 형식의 URL형태로 요청 |
X application/json 방식일 경우 사용 가능 |
profileImageFile | Multipart File |
프로필이미지 사이즈, 용량, 파일형식 300x300 이상 (1:1), 500KB, JPG/JPEG/PNG 로컬 파일 경로 입력 |
X multipart/form-data 방식일 경우 사용 가능 |
imageFileUrl | String |
홍보이미지 사이즈, 용량, 파일형식 500x500 이상 (1:1), 500KB, JPG/JPEG/PNG 1200x600 이상 (2:1), 500KB, JPG/JPEG/PNG 720x1280 이상 (9:16), 500KB, JPG/JPEG/PNG http:// 또는 https:// 형식의 유효한 형식 입력 |
application/json 방식일 경우 필수 |
imageFile | Multipart File |
홍보이미지 사이즈, 용량, 파일형식 500x500 이상 (1:1), 500KB, JPG/JPEG/PNG 1200x600 이상 (2:1), 500KB, JPG/JPEG/PNG 720x1280 이상 (9:16), 500KB, JPG/JPEG/PNG 로컬 파일 경로 입력 |
multipart/form-data 방식일 경우 필수 |
title | String |
타이틀 최대 25자 |
O |
profileName | String |
프로필 이름 최대 20자 |
O |
description | String |
홍보문구 최대 45자 |
O |
actionButton | ActionButton |
행동유도버튼 | O |
pcLandingUrl | String |
PC 랜딩 URL PC용 URL로 http:// 또는 https:// 유효한 형식 입력 |
X |
mobileLandingUrl | String |
모바일 랜딩 URL 모바일용 URL로 http:// 또는 https:// 유효한 형식 입력 |
X |
rspvLandingUrl | String |
반응형 랜딩 URL 반응형 URL로 http:// 또는 https:// 유효한 형식 입력 |
X |
altText | String |
소재 설명 최대 30자 장애인에게 음성 안내되는 내용으로 특수문자는 사용 불가능 |
O |
name | String |
소재 이름 최대 40자 요청 시 포함되지 않으면 생성 시의 이름으로 대체 |
X |
opinion | String |
의견(최대: 1,000자) | X |
opinionProofFileUrlList | String[] |
증빙application/json 방식 요청 시 사용 가능http:// 또는 https:// 형식의 증빙 파일 정보JPG/JPEG/PNG/PDF 형식 지원 최대 10개, 전체 파일 합계 용량 10MB 이하 |
X |
opinionProofFileList | Multipart File[] |
증빙multipart/form-data 방식 요청 시 사용 가능JPG/JPEG/PNG/PDF 형식 지원 최대 10개, 전체 파일 합계 용량 10MB 이하 |
X |
랜딩 URL은 총 3종류가 있습니다. PC용 URL(pcLandingUrl), 모바일용 URL(mobileLandingUrl), 반응형 URL(rspvLandingUrl)입니다. 랜딩 URL은 개별적으로는 필수(Required)가 아니지만 최소 1개 이상의 랜딩 URL을 필수로 설정해야 합니다. 디스플레이 광고 소재 중 비디오 네이티브와 이미지 박스는 종류별 랜딩 URL을 제공하지 않습니다.
이름 | 타입 | 설명 |
---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
creativeId | Long |
소재 번호 소재 수정사항 심사 중, 수정사항 심사 보류 상태일 경우 임시로 발급된 신규 소재 번호 그 외 심사 상태에서는 원본 소재 번호와 동일함 |
adGroupId | Long |
광고그룹 번호 |
format | String |
소재 유형 IMAGE_BANNER |
image | Image |
업로드 된 홍보 이미지 |
landingInfo | LandingInfo |
랜딩 정보 |
pcLandingUrl | String |
랜딩 URL (PC용 URL) |
mobileLandingUrl | String |
랜딩 URL (모바일용 URL) |
rspvLandingUrl | String |
랜딩 URL (반응형 URL) |
altText | String |
소재 설명 |
frequencyCapType | String |
게재빈도 자동 설정 종류 |
frequencyCap | Integer |
게재빈도 |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
name | String |
소재 이름 |
reviewStatus | String |
심사 상태 APPROVED(승인), WAITING(심사중), REJECTED(심사보류), MONITORING_REJECTED(관리자정지) 중 하나 |
statusDescription | String |
소재의 게재와 관련된 현재 상태 |
opinionProof | OpinionFile[] |
심사 처리를 위한 의견, 증빙자료 파일 목록 |
createdDate | String |
소재 생성일시 |
lastModifiedDate | String |
소재 마지막 수정일시 |
rejectedReason | Array |
소재 심사 사유 (비어있는 배열) |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
creativeId | Long |
소재 번호 소재 수정사항 심사 중, 수정사항 심사 보류 상태일 경우 임시로 발급된 신규 소재 번호 그 외 심사 상태에서는 원본 소재 번호와 동일함 |
adGroupId | Long |
광고그룹 번호 |
format | String |
소재 유형 IMAGE_NATIVE |
profileImage | Image |
업로드 된 프로필 이미지 |
image | Image |
업로드 된 홍보 이미지 |
title | String |
타이틀 |
profileName | String |
프로필 이름 |
description | String |
홍보문구 |
actionButton | String |
행동유도버튼 |
pcLandingUrl | String |
랜딩 URL (PC용 URL) |
mobileLandingUrl | String |
랜딩 URL (모바일용 URL) |
rspvLandingUrl | String |
랜딩 URL (반응형 URL) |
altText | String |
소재 설명 |
frequencyCapType | String |
게재빈도 자동 설정 종류 |
frequencyCap | Integer |
게재빈도 |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
name | String |
소재 이름 |
reviewStatus | String |
심사 상태 APPROVED(승인), WAITING(심사중), REJECTED(심사보류), MONITORING_REJECTED(관리자정지) 중 하나 |
statusDescription | String |
소재의 게재와 관련된 현재 상태 |
opinionProof | OpinionFile[] |
심사 처리를 위한 의견, 증빙자료 파일 목록 |
createdDate | String |
소재 생성일시 |
lastModifiedDate | String |
소재 마지막 수정일시 |
rejectedReason | Array |
소재 심사 사유 (비어있는 배열) |
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
"id":1234,
"adGroupId":5678,
"format":"IMAGE_BANNER",
"imageFileUrl":"http://www.company.com/images/sample_image_banner.jpg",
"altText":"소재설명_수정",
"mobileLandingUrl":"http://www.daum.net",
"name":"이미지_수정"
}'
curl -X POST "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
"id":1234,
"adGroupId":5678,
"format":"IMAGE_NATIVE",
"profileImageFileUrl":"http://www.company.com/images/sample_image_native.jpg",
"imageFileUrl":"http://www.company.com/images/sample_image_banner.jpg",
"altText":"소재설명_수정",
"title":"타이틀_수정",
"profileName":"프로필이름_수정",
"description":"홍보문구_수정",
"actionButton":"JOIN",
"mobileLandingUrl":"http://www.daum.net",
"name":"네이티브_소재_수정"
}'
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: multipart/form-data" \
-F "id=1234" \
-F "adGroupId=5678" \
-F "format=IMAGE_BANNER" \
-F "imageFile=@로컬_640X200_이미지_경로" \
-F "altText=소재설명_수정" \
-F "mobileLandingUrl=http://www.daum.net"
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: multipart/form-data" \
-F "id=1234" \
-F "adGroupId=5678" \
-F "format=IMAGE_NATIVE" \
-F "profileImageFile=@로컬_300X300_이미지_경로" \
-F "imageFile=@로컬_640X480_이미지_경로" \
-F "altText=소재설명_수정" \
-F "title=타이틀_수정" \
-F "profileName=프로필이름_수정" \
-F "description=홍보문구_수정" \
-F "actionButton=JOIN" \
-F "mobileLandingUrl=http://www.daum.net"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1234,
"creativeId": 1235,
"adGroupId": 5678,
"format": "IMAGE_BANNER",
"name": "이미지_수정",
"landingInfo": {
"landingType": "AD_VIEW",
"communicatorAdViewId": 1
}
"pcLandingUrl": null,
"mobileLandingUrl": null,
"rspvLandingUrl": null,
"frequencyCap": null,
"frequencyCapType": "AUTO",
"config": "ON",
"systemConfig": "ON",
"reviewStatus": "WAITING",
"image": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_xxx.jpg",
"fileName": "sample_image_banner.jpg",
"width": 640,
"height": 100,
"size": 50000
},
"altText": "소재설명_수정",
"statusDescription": "심사중",
"createdDate": "2020-01-01T00:00:00.00000",
"lastModifiedDate": "2020-01-01T00:00:00.000000",
"rejectedReason": []
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1234,
"creativeId": 1235,
"adGroupId": 5678,
"format": "IMAGE_NATIVE",
"name": "네이티브_소재_수정",
"pcLandingUrl": null,
"mobileLandingUrl": "http://www.daum.net",
"rspvLandingUrl": null,
"frequencyCap": null,
"frequencyCapType": "AUTO",
"config": "ON",
"systemConfig": "ON",
"reviewStatus": "WAITING",
"image": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_xxx.jpg",
"fileName": "sample_image_banner.jpg",
"width": 640,
"height": 480,
"size": 100000
},
"altText": "소재설명_수정",
"title": "타이틀",
"description": "홍보문구_수정",
"actionButton": "JOIN",
"profileName": "프로필이름_수정",
"profileImage": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_xxx.jpg",
"fileName": "sample_image_native.jpg",
"width": 300,
"height": 300,
"size": 50000
},
"statusDescription": "심사중",
"createdDate": "2020-01-01T00:00:00.000000",
"lastModifiedDate": "2020-01-01T00:00:00.000000",
"rejectedReason": []
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/creatives/copy |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
디스플레이 소재를 복사합니다. 최대 20개의 소재 복사를 요청할 수 있으나 그룹, 캠페인, 계정의 최대 생성 가능 소재 개수를 초과할 경우 복사 실패할 수 있습니다.
캠페인 유형X목표가 카카오 비즈보드X방문, 카카오 비즈보드X전환, 디스플레이X방문, 디스플레이X전환인 캠페인 하위의 이미지 배너, 이미지 네이티브 소재만 복사가 가능합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 POST
로 광고계정 번호와 복사할 소재가 있는 캠페인 번호, 복사할 소재 번호 목록을 지정하여 요청합니다. 성공 시 복사된 소재 정보의 배열을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청이 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
adGroupId | Long |
소재들이 복사될 광고그룹 번호(100개 제한) | O |
creativeIds | Long[] |
복사할 소재 번호 목록 | O |
이름 | 타입 | 설명 |
---|---|---|
- | DisplayCreative[] |
소재 정보 목록 |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
creativeId | Long |
소재 번호 소재 수정사항 심사 중, 수정사항 심사 보류 상태일 경우 임시로 발급된 신규 소재 번호 그 외 심사 상태에서는 원본 소재 번호와 동일함 |
name | String |
소재명 |
format | String |
소재 유형 IMAGE_BANNER(이미지 배너), IMAGE_NATIVE(이미지 네이티브) 중 하나 |
landingUrl | String |
랜딩 URL |
frequencyCap | Integer |
게재빈도 |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
systemConfig | String |
소재 시스템 상태 ON, ADMIN_STOP 중 하나 |
reviewStatus | String |
심사 상태 APPROVED(승인), WAITING(심사중), REJECTED(심사보류), MODIFICATION_WAITING(수정사항심사중), MODIFICATION_REJECTED(수정사항심사보류) 중 하나 |
creativeStatus | String |
소재의 운영 상태 OPERATING(운영가능), UNAPPROVED(심사미승인), INVALID_DATE(기간오류), MONITORING_REJECTED(관리자정지), OFF(사용자OFF), DELETED(삭제), ADGROUP_UNAVAILABLE(광고그룹 운영불가) 중 하나 |
statusDescription | String |
소재의 게재와 관련된 현재 상태 |
image | Image |
IMAGE_BANNER, IMAGE_NATIVE, VIDEO_NATIVE 소재의 메인 이미지 |
landingInfo | LandingInfo |
랜딩 정보 |
altText | String |
IMAGE_BANNER 소재의 이미지 대체 설명문구 |
title | String |
IMAGE_NATIVE, VIDEO_NATIVE 소재의 타이틀 |
description | String |
IMAGE_NATIVE, VIDEO_NATIVE 소재의 홍보문구 |
actionButton | String |
IMAGE_NATIVE, VIDEO_NATIVE 소재의 행동유도버튼 |
profileName | String |
IMAGE_NATIVE, VIDEO_NATIVE 소재의 프로필 이름 |
profileImage | Image |
업로드 된 프로필 이미지 |
video | Video |
VIDEO_NATIVE 소재의 비디오 |
rejectedReason | RejectedReason |
소재 보류 사유 |
opinion | String |
심사 처리를 위한 참조 의견 |
opinionProof | OpinionFile[] |
심사 처리를 위한 의견, 증빙자료 파일 목록 |
createdDate | String |
소재 생성일시 |
lastModifiedDate | String |
소재 마지막 수정일시 |
curl -X POST "https://apis.moment.kakao.com/openapi/v4/creatives/copy" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-d '{
"adGroupId" : 23456,
"creativeIds" : [34567,34568]
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
{
"id": 35678,
"creativeId": 35678,
"adGroupId": 23456,
"format": "IMAGE_BANNER",
"name": "이미지 소재 1",
"landingInfo": {
"landingType": "URL",
"url": "http://m.daum.net"
},
"pcLandingUrl": null,
"mobileLandingUrl": "http://m.daum.net",
"rspvLandingUrl": null,
"frequencyCap": null,
"frequencyCapType": "AUTO",
"config": "ON",
"systemConfig": "ON",
"reviewStatus": "APPROVED",
"creativeStatus": "OPERATING",
"image": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_111.jpg",
"fileName": "sample_image_banner_111.jpg",
"width": 640,
"height": 480,
"size": 100000
},
"altText": "이미지설명문구 1",
"statusDescription": "운영중",
"rejectedReason": [],
"createdDate": "2020-01-01T00:00:00.000000",
"lastModifiedDate": "2020-01-01T00:00:00.000000"
},
{
"id": 35679,
"creativeId": 35678,
"adGroupId": 23456,
"format": "IMAGE_BANNER",
"name": "이미지 소재 2",
"landingInfo": {
"landingType": "URL",
"url": "http://m.daum.net"
},
"pcLandingUrl": null,
"mobileLandingUrl": "http://m.daum.net",
"rspvLandingUrl": null,
"frequencyCap": null,
"frequencyCapType": "AUTO",
"config": "ON",
"systemConfig": "ON",
"reviewStatus": "APPROVED",
"creativeStatus": "OPERATING",
"image": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_222.jpg",
"fileName": "sample_image_banner_222.jpg",
"width": 640,
"height": 480,
"size": 100000
},
"altText": "이미지설명문구 2",
"statusDescription": "운영중",
"rejectedReason": [],
"createdDate": "2020-01-01T00:00:00.000000",
"lastModifiedDate": "2020-01-01T00:00:00.000000"
}
]
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/opinionProof |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
소재의 의견증빙 정보를 조회합니다. 헤더에 액세스 토큰(Access token)을 담아 GET
으로 요청합니다. 요청이 성공하면 응답 본문에 JSON
객체로 소재의 의견증빙 정보를 받습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
ID | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
O |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
의견증빙 번호 |
opinion | String |
의견 |
opinionProofFileList | OpinionFile[] |
파일 목록 |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/opinionProof" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1,
"opinion": "의견증빙",
"opinionProofFileList": [
{
"id": 11,
"originalFileName": "sample_1.jpg",
"downloadUrl": "https://xxx.kakao.com/sample_1.jpg"
}
]
}
{
"code": -813,
"msg": "KakaoMomentException",
"extras": {
"detailCode": 75637,
"detailMsg": "의견증빙 정보가 존재하지 않습니다."
}
}