이 문서는 디스플레이 소재 API 사용 방법을 안내합니다.
2024년 9월 5일 업데이트로 아래 디스플레이 소재 유형이 추가되었습니다.
캠페인 유형 | 소재 유형 | 홍보 이미지 | 프로필 이미지 |
---|---|---|---|
디스플레이 | 이미지 카탈로그(CATALOG_MANUAL) | 슬라이드 내 홍보 이미지: 500x500 이상 (9:16), 500KB, JPG/JPEG/PNG 최소 4개, 최대 10개 설정 가능 |
300x300 이상 (1:1), 500KB, JPG/JPEG/PNG |
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 사용 |
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/creatives |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
디스플레이 소재를 생성합니다. 소재 생성 요청은 소재 유형(format)을 반드시 이미지 배너(IMAGE_BANNER), 이미지 네이티브(IMAGE_NATIVE), 이미지 카탈로그(CATALOG_MANUAL) 중 하나로 명시해야 합니다. 소재 유형에 따라 전달해야 하는 파라미터 종류가 다릅니다. 예를 들어 이미지 배너는 imageFileUrl
을, 이미지 네이티브는 imageFileUrl
과 profileImageFileUrl
을, 이미지 카탈로그는 assetGroups
리스트와 profileImageFileUrl
을 각각 전달합니다.
소재 생성하기 API는 이미지 등록을 위해 application/json
과 multipart/form-data
두 가지 Content-Type
을 지원합니다. 어느 방식으로 요청하더라도 소재 생성 결과는 같습니다.
imageFileUrl
파라미터로 http://
또는 https://
URL 형식의 소재 이미지 경로 전달imageFile
파라미터로 로컬 파일 경로 전달비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 POST
로 요청하며, 요청이 성공하면 응답 본문에 JSON
객체로 생성된 소재의 상세 정보를 목록으로 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
비즈보드 X 도달, 다음쇼핑 유형의 캠페인 하위에는 소재 생성이 불가능합니다.
이 API는 사용자 계정, 광고계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.
랜딩 URL은 세 종류입니다.
PC용 URL(pcLandingUrl), 모바일용 URL(mobileLandingUrl), 반응형 URL(rspvLandingUrl) 으로 이루어진 랜딩 URL은 개별적으로는 필수(Required)가 아니지만 최소 1개 이상의 랜딩 URL을 필수로 설정해야 합니다.
이때, 반응형 URL은 다른 URL과 함께 설정이 불가능하여 단독으로만 설정 가능합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_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 |
소재 이름 최대 50자 설정하지 않은 경우 {캠페인 유형}_{캠페인 목표}_{현재시간}_{소재 사이즈} 로 생성 |
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 |
소재 이름 최대 50자 설정하지 않은 경우 {캠페인 유형}_{캠페인 목표}_{현재시간}_{소재 사이즈} 로 생성 |
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 |
소재 유형 CATALOG_MANUAL (고정값) |
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 방식일 경우 필수 |
assetGroups | AssetGroup[] |
CATALOG_MANUAL(이미지 카탈로그) 소재의 슬라이드 아이템(최소 4개, 최대: 10개) | |
profileName | String |
프로필 이름 최대 20자 |
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 |
name | String |
소재 이름 최대 50자 설정하지 않은 경우 {캠페인 유형}_{캠페인 목표}_{현재시간}_{소재 사이즈} 로 생성 |
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를 사용 |
channelPostId | Long |
CHANNEL_POST (채널 소식) 랜딩 사용시 채널 소식 아이디 연동 가능한 채널 소식 랜딩 유형 목록 보기 API를 통해 조회되는 소식 번호를 사용 |
이름 | 설명 |
---|---|
PF_BOT | 챗봇 |
AD_VIEW | 애드뷰 |
CHANNEL_WEBVIEW | 채널웹뷰 |
BIZ_FORM | 비즈니스폼 |
CHANNEL_POST | 채널 소식 |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
애드뷰 번호 |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
ordering | Integer |
슬라이드 정렬 순번 생성 요청 시 필수 수정 요청 시 사용 불가, 본문 리스트 순서대로 자동 지정 |
O |
imageFileUrl | String |
슬라이드 이미지 사이즈, 용량, 파일형식 300x300 이상 (1:1), 500KB, JPG/JPEG/PNG http:// 또는 https:// 형식의 유효한 형식 입력 |
application/json 방식일 경우 필수 |
imageFile | Multipart File |
슬라이드 이미지 사이즈, 용량, 파일형식 300x300 이상 (1:1), 500KB, JPG/JPEG/PNG 로컬 파일 경로 입력 |
multipart/form-data 방식일 경우 필수 |
title | String |
타이틀(최대: 25자) | O |
pcLandingUrl | String |
PC 대표 랜딩 URL PC용 URL로 http:// 또는 https:// 유효한 형식 입력 |
X |
mobileLandingUrl | String |
모바일 대표 랜딩 URL 모바일용 URL로 http:// 또는 https:// 유효한 형식 입력 |
X |
rspvLandingUrl | String |
반응형 대표 랜딩 URL 반응형 URL로 http:// 또는 https:// 유효한 형식 입력 |
X |
description | String |
홍보 문구(최대: 40자) | X |
priceAmount | String |
가격 정보(최소: 0, 최대: 9999999999, CurrencyCode 가 KRW , JPY 일 경우 정수만 입력 가능, USD , EUR 일 경우 소수점 둘째 자리까지 입력 가능)가격 정보 요청 시 통화 정보( priceCurrencyCode ) 함께 요청 필수 |
X |
priceCurrencyCode | String |
통화 정보KRW , USD , JPY , EUR 중 하나가격 정보( priceAmount ), 할인 가격 정보(discountedPriceAmount ) 요청 시 함께 요청 필수 |
X |
discountedPriceAmount | String |
할인 가격 정보(최소: 0, 최대: 9999999999, CurrencyCode 가 KRW , JPY 일 경우 정수만 입력 가능, USD , EUR 일 경우 소수점 둘째 자리까지 입력 가능)가격 정보( priceAmount )보다 1% 이상 작은 값으로만 요청 가능할인 가격 정보 요청 시 가격 정보( priceAmount ), 통화 정보(priceCurrencyCode ) 함께 요청 필수 |
X |
이름 | 타입 | 설명 |
---|---|---|
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 |
소재 심사 사유 (비어있는 배열) |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
creativeId | Long |
소재 번호 소재 수정사항 심사 중, 수정사항 심사 보류 상태일 경우 임시로 발급된 신규 소재 번호 그 외 심사 상태에서는 원본 소재 번호와 동일함 |
adGroupId | Long |
광고그룹 번호 |
format | String |
소재 유형 CATALOG_MANUAL |
profileImage | Image |
업로드 된 프로필 이미지 |
profileName | String |
프로필 이름 |
assetGroups | AssetGroup[] |
슬라이드 아이템 |
actionButton | String |
행동유도버튼 |
pcLandingUrl | String |
랜딩 URL (PC용 URL) |
mobileLandingUrl | String |
랜딩 URL (모바일용 URL) |
rspvLandingUrl | String |
랜딩 URL (반응형 URL) |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
systemConfig | String |
소재 시스템 상태 ON, ADMIN_STOP 중 하나 |
name | String |
소재 이름 |
reviewStatus | String |
심사 상태 APPROVED(승인), WAITING(심사중), REJECTED(심사보류), MONITORING_REJECTED(관리자정지) 중 하나 |
statusDescription | String |
소재의 게재와 관련된 현재 상태 |
creativeStatus | String |
소재의 운영 상태 OPERATING(운영가능), UNAPPROVED(심사미승인), INVALID_DATE(기간오류), MONITORING_REJECTED(관리자정지), OFF(사용자OFF), DELETED(삭제), ADGROUP_UNAVAILABLE(광고그룹 운영불가) 중 하나 |
opinionProof | OpinionFile[] |
심사 처리를 위한 의견, 증빙자료 파일 목록 |
createdDate | String |
소재 생성일시 |
lastModifiedDate | String |
소재 마지막 수정일시 |
rejectedReason | Array |
소재 심사 사유 (비어있는 배열) |
curl -X POST "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${BUSINESS_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 ${BUSINESS_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 ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
"adGroupId": 1234,
"format": "CATALOG_MANUAL",
"profileName": "프로필이름",
"profileImageFileUrl": "https://example.com/test/profileImageProfile.jpg",
"assetGroups": [
{
"ordering": 0,
"imageFileUrl": "https://example.com/test/asset1.jpg",
"title": "title1",
"rspvLandingUrl": "https://www.kakakcorp.com/"
},
{
"ordering": 1,
"imageFileUrl": "https://example.com/test/asset2.jpg",
"title": "title2",
"rspvLandingUrl": "https://www.kakakcorp.com/"
},
{
"ordering": 2,
"imageFileUrl": "https://example.com/test/asset3.jpg",
"title": "title3",
"rspvLandingUrl": "https://www.kakakcorp.com/"
},
{
"ordering": 3,
"imageFileUrl": "https://example.com/test/asset4.jpg",
"title": "title4",
"rspvLandingUrl": "https://www.kakakcorp.com/"
}
],
"rspvLandingUrl": "https://www.kakakcorp.com",
"actionButton": "JOIN"
}'
curl -X POST "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${BUSINESS_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 ${BUSINESS_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"
curl -X POST 'https://apis.moment.kakao.com/openapi/v4/creatives' \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: multipart/form-data" \
-F "adGroupId=1234" \
-F "format=CATALOG_MANUAL" \
-F "profileName=프로필이름" \
-F "profileImageFile=@로컬_이미지_경로" \
-F "rspvLandingUrl=https://www.kakaocorp.com" \
-F "actionButton=JOIN" \
-F "assetGroups[0].ordering=0" \
-F "assetGroups[0].imageFile=@로컬_이미지1_경로" \
-F "assetGroups[0].title=ImageTitle1" \
-F "assetGroups[0].rspvLandingUrl=https://www.kakaocorp.com" \
-F "assetGroups[1].ordering=1" \
-F "assetGroups[1].imageFile=@로컬_이미지2_경로" \
-F "assetGroups[1].title=ImageTitle2" \
-F "assetGroups[1].rspvLandingUrl=https://www.kakaocorp.com" \
-F "assetGroups[2].ordering=2" \
-F "assetGroups[2].imageFile=@로컬_이미지3_경로" \
-F "assetGroups[2].title=ImageTitle3" \
-F "assetGroups[2].rspvLandingUrl=https://www.kakaocorp.com" \
-F "assetGroups[3].ordering=3" \
-F "assetGroups[3].imageFile=@로컬_이미지4_경로" \
-F "assetGroups[3].title=ImageTitle4" \
-F "assetGroups[3].rspvLandingUrl=https://www.kakaocorp.com"
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": []
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1324,
"creativeId": 1235,
"format": "CATALOG_MANUAL",
"name": "모먼트_소재_등록",
"adGroupId": 1234,
"pcLandingUrl": null,
"mobileLandingUrl": null,
"rspvLandingUrl": "https://www.daum.net",
"frequencyCap": null,
"frequencyCapType": "AUTO",
"config": "ON",
"systemConfig": "ON",
"reviewStatus": "WAITING",
"creativeStatus": "UNAPPROVED",
"assetGroups": [
{
"assetGroupId": 1234,
"ordering": 0,
"image": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_xxx.jpeg",
"fileName": "sample.jpg",
"width": 500,
"height": 500,
"size": 18238,
"mimeType": "image/jpeg"
},
"title": "타이틀",
"rspvLandingUrl": "https://www.kakaocorp.com"
},
{
"assetGroupId": 1235,
"ordering": 1,
"image": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_xxx.jpeg",
"fileName": "sample.jpg",
"width": 500,
"height": 500,
"size": 43537,
"mimeType": "image/jpeg"
},
"title": "타이틀",
"rspvLandingUrl": "https://www.kakaocorp.com"
},
{
"assetGroupId": 1236,
"ordering": 2,
"image": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_xxx.jpeg",
"fileName": "sample.jpeg",
"width": 900,
"height": 900,
"size": 45241,
"mimeType": "image/jpeg"
},
"title": "타이틀",
"rspvLandingUrl": "https://www.kakaocorp.com"
},
{
"assetGroupId": 1237,
"ordering": 3,
"image": {
"url": "http://xxx.kakao.co.kr/sample_image_banner_xxx.jpeg",
"fileName": "sample.png",
"width": 1080,
"height": 1080,
"size": 266029,
"mimeType": "image/png"
},
"title": "타이틀",
"rspvLandingUrl": "https://www.kakaocorp.com"
}
],
"profileName": "프로필이름",
"profileImage":{
"url": "http://xxx.kakao.co.kr/sample_image_native_xxx.jpg",
"fileName": "sample_image_native.jpeg",
"width": 300,
"height": 300,
"size": 50000
},
"videoSkippableType": null,
"statusDescription": "심사중",
"rejectedReason": [],
"createdDate": "2020-01-01T00:00:00.000000",
"lastModifiedDate": "2020-01-01T00:00:00.000000",
"hasExpandable": false,
"opinionProof": null
}
메서드 | URL | 인증 방식 |
---|---|---|
PUT |
https://apis.moment.kakao.com/openapi/v4/creatives |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
디스플레이 소재를 수정합니다. 소재 유형에 따라 전달해야 하는 파라미터 종류가 다릅니다. 예를 들어 이미지 배너(IMAGE_BANNER)는 imageFileUrl
을, 이미지 네이티브(IMAGE_NATIVE)는 imageFileUrl
과 profileImageFileUrl
을, 이미지 카탈로그(CATALOG_MANUAL)는 assetGroups
리스트와 profileImageFileUrl
을 각각 전달합니다.
소재 수정 API는 이미지 등록을 위해 application/json
과 multipart/form-data
두 가지 Content-Type
을 지원합니다. application/json
방식으로 호출할 때는 imageFileUrl
파라미터로 http://
또는 https://
URL 형식으로 소재 이미지를 전달해야 합니다. multipart/form-data
방식으로 호출할 때는 imageFile
파라미터에 경로를 지정해 로컬에 저장된 파일을 전달할 수 있습니다. 어느 방식으로 요청하더라도 소재 수정 결과는 같습니다.
imageFileUrl
또는 profileImageFileUrl
이 요청 Body
에 없으면 기존에 등록된 이미지를 활용합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 PUT
으로 요청하며, 성공 시 응답 본문에 JSON
객체로 소재 상세 정보를 목록으로 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
비즈보드 X 도달, 다음쇼핑 유형의 캠페인 하위에는 소재 수정이 불가능합니다.
이 API는 사용자 계정, 광고계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.
랜딩 URL은 세 종류입니다.
PC용 URL(pcLandingUrl), 모바일용 URL(mobileLandingUrl), 반응형 URL(rspvLandingUrl) 으로 이루어진 랜딩 URL은 개별적으로는 필수(Required)가 아니지만 최소 1개 이상의 랜딩 URL을 필수로 설정해야 합니다.
이때, 반응형 URL은 다른 URL과 함께 설정이 불가능하여 단독으로만 설정 가능합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_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 |
소재 이름 최대 50자 요청 시 포함되지 않으면 생성 시의 이름으로 대체 |
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:// 형식의 유효한 형식 입력 |
X 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 로컬 파일 경로 입력 |
X 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 |
소재 이름 최대 50자 요청 시 포함되지 않으면 생성 시의 이름으로 대체 |
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 |
소재 유형 CATALOG_MANUAL (고정값) |
O |
profileImageFileUrl | String |
프로필이미지 사이즈, 용량, 파일형식 300x300 이상 (1:1), 500KB, JPG/JPEG/PNG http:// 또는 https:// 형식의 유효한 형식 입력 |
X application/json 방식인 경우 사용 가능 |
profileImageFile | Multipart File |
프로필이미지 사이즈, 용량, 파일형식 300x300 이상 (1:1), 500KB, JPG/JPEG/PNG 로컬 파일 경로 입력 |
X multipart/form-data 방식인 경우 사용 가능 |
assetGroups | AssetGroup[] |
CATALOG_MANUAL(이미지 카탈로그) 소재의 슬라이드 아이템(최소 4개, 최대: 10개) | O |
profileName | String |
프로필 이름 최대 20자 |
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 |
name | String |
소재 이름 최대 50자 설정하지 않은 경우 {캠페인 유형}_{캠페인 목표}_{현재시간}_{소재 사이즈} 로 생성 |
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 |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
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 |
소재 심사 사유 (비어있는 배열) |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
creativeId | Long |
소재 번호 소재 수정사항 심사 중, 수정사항 심사 보류 상태일 경우 임시로 발급된 신규 소재 번호 그 외 심사 상태에서는 원본 소재 번호와 동일함 |
adGroupId | Long |
광고그룹 번호 |
format | String |
소재 유형 CATALOG_MANUAL |
profileImage | Image |
업로드 된 프로필 이미지 |
profileName | String |
프로필 이름 |
assetGroups | AssetGroup[] |
슬라이드 아이템 |
actionButton | String |
행동유도버튼 |
pcLandingUrl | String |
랜딩 URL (PC용 URL) |
mobileLandingUrl | String |
랜딩 URL (모바일용 URL) |
rspvLandingUrl | String |
랜딩 URL (반응형 URL) |
frequencyCapType | String |
게재빈도 자동 설정 종류 |
frequencyCap | Integer |
게재빈도 |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
systemConfig | String |
소재 시스템 상태 ON, ADMIN_STOP 중 하나 |
name | String |
소재 이름 |
reviewStatus | String |
심사 상태 APPROVED(승인), WAITING(심사중), REJECTED(심사보류), MONITORING_REJECTED(관리자정지) 중 하나 |
creativeStatus | String |
소재의 운영 상태 OPERATING(운영가능), UNAPPROVED(심사미승인), INVALID_DATE(기간오류), MONITORING_REJECTED(관리자정지), OFF(사용자OFF), DELETED(삭제), ADGROUP_UNAVAILABLE(광고그룹 운영불가) 중 하나 |
statusDescription | String |
소재의 게재와 관련된 현재 상태 |
opinionProof | OpinionFile[] |
심사 처리를 위한 의견, 증빙자료 파일 목록 |
createdDate | String |
소재 생성일시 |
lastModifiedDate | String |
소재 마지막 수정일시 |
rejectedReason | Array |
소재 심사 사유 (비어있는 배열) |
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${BUSINESS_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 ${BUSINESS_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 POST "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
"id": 1
"adGroupId": 1234,
"format": "CATALOG_MANUAL",
"profileName": "프로필이름_수정",
"name":"카탈로그_소재_수정",
"profileImageFileUrl": "https://example.com/test/profileImageProfile.jpg",
"assetGroups": [
{
"ordering": 0,
"imageFileUrl": "https://example.com/test/asset1.jpg",
"title": "title1",
"rspvLandingUrl": "https://www.kakakcorp.com/"
},
{
"ordering": 1,
"imageFileUrl": "https://example.com/test/asset2.jpg",
"title": "title2",
"rspvLandingUrl": "https://www.kakakcorp.com/"
},
{
"ordering": 2,
"imageFileUrl": "https://example.com/test/asset3.jpg",
"title": "title3",
"rspvLandingUrl": "https://www.kakakcorp.com/"
},
{
"ordering": 3,
"imageFileUrl": "https://example.com/test/asset4.jpg",
"title": "title4",
"rspvLandingUrl": "https://www.kakakcorp.com/"
}
],
"rspvLandingUrl": "https://www.kakakcorp.com",
"actionButton": "JOIN"
}'
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer ${BUSINESS_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 ${BUSINESS_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"
curl -X PUT 'https://apis.moment.kakao.com/openapi/v4/creatives' \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: multipart/form-data" \
-F "id=1" \
-F "adGroupId=1234" \
-F "format=CATALOG_MANUAL" \
-F "profileName=프로필이름_수정" \
-F "profileImageFile=@로컬_이미지_경로" \
-F "name=카탈로그_소재_수정" \
-F "rspvLandingUrl=https://www.kakaocorp.com" \
-F "actionButton=JOIN" \
-F "assetGroups[0].ordering=0" \
-F "assetGroups[0].imageFile=@로컬_이미지1_경로" \
-F "assetGroups[0].title=ImageTitle1" \
-F "assetGroups[0].rspvLandingUrl=https://www.kakaocorp.com" \
-F "assetGroups[1].ordering=1" \
-F "assetGroups[1].imageFile=@로컬_이미지2_경로" \
-F "assetGroups[1].title=ImageTitle2" \
-F "assetGroups[1].rspvLandingUrl=https://www.kakaocorp.com" \
-F "assetGroups[2].ordering=2" \
-F "assetGroups[2].imageFile=@로컬_이미지3_경로" \
-F "assetGroups[2].title=ImageTitle3" \
-F "assetGroups[2].rspvLandingUrl=https://www.kakaocorp.com" \
-F "assetGroups[3].ordering=3" \
-F "assetGroups[3].imageFile=@로컬_이미지4_경로" \
-F "assetGroups[3].title=ImageTitle4" \
-F "assetGroups[3].rspvLandingUrl=https://www.kakaocorp.com"
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": []
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1,
"creativeId": 2,
"format": "CATALOG_MANUAL",
"profileName": "프로필이름_수정",
"profileImage": {
"url": "http://xxx.kakao.co.kr/sample_image_native_xxx.jpg",
"fileName": "sample_image_native.jpeg",
"width": 300,
"height": 300,
"size": 50000
},
"name": "카탈로그_소재_수정",
"adGroupId": 1234,
"landingInfo": null,
"pcLandingUrl": null,
"mobileLandingUrl": null,
"rspvLandingUrl": "https://www.kakaocorp.com",
"frequencyCap": null,
"frequencyCapType": "AUTO",
"config": "ON",
"systemConfig": "ON",
"reviewStatus": "WAITING",
"creativeStatus": "UNAPPROVED",
"image": {
"url": "image URL",
"fileName": "image.jpg",
"width": 640,
"height": 640,
"size": 50000
},
"assetGroups": [
{
"assetGroupId": 1,
"ordering": 0,
"image": {
"url": "image1 URL",
"fileName": "image1.jpg",
"width": 640,
"height": 640,
"size": 50000
},
"title": "이미지1제목",
"rspvLandingUrl": "https://www.kakaocorp.com"
},
{
"assetGroupId": 2,
"ordering": 1,
"image": {
"url": "image2 URL",
"fileName": "image2.jpg",
"width": 640,
"height": 640,
"size": 50000
},
"title": "이미지2제목",
"rspvLandingUrl": "https://www.kakaocorp.com"
},
{
"assetGroupId": 3,
"ordering": 2,
"image": {
"url": "image3 URL",
"fileName": "image3.jpg",
"width": 640,
"height": 640,
"size": 50000
},
"title": "이미지3제목",
"rspvLandingUrl": "https://www.kakaocorp.com"
},
{
"assetGroupId": 4,
"ordering": 3,
"image": {
"url": "image4 URL",
"fileName": "image4.jpg",
"width": 640,
"height": 640,
"size": 50000
},
"title": "이미지4제목",
"rspvLandingUrl": "https://www.kakaocorp.com"
}
],
"statusDescription": "심사중",
"rejectedReason": [],
"createdDate": "2020-01-01T00:00:00.00000",
"lastModifiedDate": "2020-01-01T00:00:00.00000",
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/creatives/copy |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
디스플레이 소재를 복사합니다. 최대 20개의 소재 복사를 요청할 수 있으나 그룹, 캠페인, 계정의 최대 생성 가능 소재 개수를 초과할 경우 복사 실패할 수 있습니다.
캠페인 유형X목표가 카카오 비즈보드X방문, 카카오 비즈보드X전환, 디스플레이X방문, 디스플레이X전환인 캠페인 하위의 이미지 배너, 이미지 네이티브, 이미지 카탈로그 소재만 복사가 가능합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 POST
로 광고계정 번호와 복사할 소재가 있는 캠페인 번호, 복사할 소재 번호 목록을 지정하여 요청합니다. 성공 시 복사된 소재 정보의 배열을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청이 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_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(이미지 네이티브), CATALOG_MANUAL(이미지 카탈로그) 중 하나 |
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 소재의 메인 이미지 |
assetGroups | AssetGroup[] |
CATALOG_MANUAL(이미지 카탈로그) 소재의 슬라이드 아이템 정보 |
landingInfo | LandingInfo |
랜딩 정보 |
altText | String |
IMAGE_BANNER 소재의 이미지 대체 설명문구 |
title | String |
IMAGE_NATIVE, VIDEO_NATIVE 소재의 타이틀 |
description | String |
IMAGE_NATIVE, VIDEO_NATIVE 소재의 홍보문구 |
actionButton | String |
IMAGE_NATIVE, VIDEO_NATIVE, CATALOG_MANUAL 소재의 행동유도버튼 |
profileName | String |
IMAGE_NATIVE, VIDEO_NATIVE, CATALOG_MANUAL 소재의 프로필 이름 |
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 ${BUSINESS_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 |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
소재의 의견증빙 정보를 조회합니다. 헤더에 비즈니스 토큰을 담아 GET
으로 요청합니다. 요청이 성공하면 응답 본문에 JSON
객체로 소재의 의견증빙 정보를 받습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_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 ${BUSINESS_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": "의견증빙 정보가 존재하지 않습니다."
}
}