광고 생성: 디스플레이 소재 배너 홍보 이미지 생성

이 문서는 디스플레이 소재 중 이미지 배너 소재의 홍보 이미지를 생성하는 배너 홍보 이미지 생성 API 사용 방법을 안내합니다.

이외의 디스플레이 소재와 관련된 전체 API 개발 문서는 광고 생성: 디스플레이 소재에서 확인할 수 있습니다.

배너 홍보 이미지 생성

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/v4/creative/bannerImage`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

디스플레이 소재 중 이미지 배너 소재의 홍보 이미지를 생성합니다. 홍보 이미지 생성 요청은 템플릿 유형(templateType)을 반드시 오브젝트형 배너(OBJECT), 썸네일형 배너(THUMBNAIL), 마스킹 배너(MASKING), 텍스트형 배너(TEXT) 중 하나로 명시해야 합니다. 템플릿 유형에 따라 전달해야 하는 파라미터가 다릅니다. 각 템플릿별 요청 본문의 내용을 확인합니다.

배너 홍보 이미지 생성 API는 Content-Type을 multipart/form-data만 지원합니다. 요청 시 imageFile 파라미터로 로컬 파일 경로를 전달해야 합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청하며, 요청이 성공하면 응답 본문에 JSON 객체로 생성된 소재의 상세 정보를 목록으로 포함합니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

본문: OBJECT 템플릿

이름	타입	설명	필수
templateType	`String`	템플릿 유형, 아래 중 하나 `OBJECT`: 오브젝트형 배너 `THUMBNAIL`: 썸네일형 배너 `MASKING`: 마스킹 배너 `TEXT`: 텍스트형 배너	O
mainCopy	`String`	메인 문구 (최대 30자)	O
subCopy	`String`	서브 문구 (최대 30자)	X
noticeInfo	`NoticeInfo`	고지 문구 정보	X
images	`File[]`	메인 이미지	O
badgeInfo	`BadgeInfo`	뱃지 정보	X
appIconInfo	`appIconInfo`	앱 아이콘 정보	X

본문: THUMBNAIL 템플릿

이름	타입	설명	필수
templateType	`String`	템플릿 유형, 아래 중 하나 `OBJECT`: 오브젝트형 배너 `THUMBNAIL`: 썸네일형 배너 `MASKING`: 마스킹 배너 `TEXT`: 텍스트형 배너	O
mainCopy	`String`	메인 문구 (최대 30자)	O
subCopy	`String`	서브 문구 (최대 30자)	X
noticeInfo	`NoticeInfo`	고지 문구 정보	X
thumbnailType	`String`	썸네일 유형, 아래 중 하나 `SQUARE`: 정사각형 썸네일 `BLUR`: 블러 처리 썸네일 `MULTI`: 복수 이미지 조합	O
images	`File[]`	최소 1개 ~ 최대 2개 이미지	O
badgeInfo	`BadgeInfo`	뱃지 정보	X
appIconInfo	`appIconInfo`	앱 아이콘 정보	X

본문: MASKING 템플릿

이름	타입	설명	필수
templateType	`String`	템플릿 유형, 아래 중 하나 `OBJECT`: 오브젝트형 배너 `THUMBNAIL`: 썸네일형 배너 `MASKING`: 마스킹 배너 `TEXT`: 텍스트형 배너	O
mainCopy	`String`	메인 문구 (최대 30자)	O
subCopy	`String`	서브 문구 (최대 30자)	X
noticeInfo	`NoticeInfo`	고지 문구 정보	X
maskingType	`String`	마스킹 유형, 아래 중 하나 `HALF_TOP`: 상단 반 마스킹 `HALF_BOTTOM`: 하단 반 마스킹	O
images	`File[]`	메인 이미지	O
logo	`File`	로고 이미지	O
appIconInfo	`AppIconInfo`	앱 아이콘 정보	X

본문: TEXT 템플릿

이름	타입	설명	필수
templateType	`String`	템플릿 유형, 아래 중 하나 `OBJECT`: 오브젝트형 배너 `THUMBNAIL`: 썸네일형 배너 `MASKING`: 마스킹 배너 `TEXT`: 텍스트형 배너	O
mainCopy	`String`	메인 문구 (최대 30자)	O
subCopy	`String`	서브 문구 (최대 30자)	X
noticeInfo	`NoticeInfo`	고지 문구 정보	X

NoticeInfo

이름	타입	설명	필수
noticeType	`Number`	고지 문구 유형, 아래 중 하나 `1`: 법적 고지문 `2`: 채팅방 랜딩 고지문	X
noticeText	`String`	고지 내용	X

AppIconInfo

이름	타입	설명	필수
useTalkIcon	`Boolean`	카카오톡 아이콘 사용 여부	X
iconImage	`File`	앱 아이콘 이미지	X
appIconCopy	`String`	아이콘 옆에 표시할 보조 문구	X

BadgeInfo

이름	타입	설명	필수
badgeType	`String`	배지 타입, 아래 중 하나 `FLAG`: 플래그형 `BELT`: 띠형	X
badgeColor	`String`	배지 색상, 아래 중 하나 `#EE2E04` `#FF6229` `#ED6689` `#0072DD` `#25B06D` `#6B52CB` `#121212`	X
badgeTexts	`String[]`	배지에 들어갈 문구 (최대 2개)	X

응답

이름	타입	설명
bannerImageUrl	`String`	생성된 최종 배너 URL
imageType	`String`	템플릿 타입
width	`Number`	이미지 가로 사이즈
height	`Number`	이미지 세로 사이즈

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/v4/creatives/bannerImage" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "Content-Type: multipart/form-data" \
    -F "templateType=OBJECT" \
    -F "mainCopy=메인 문구 테스트" \
    -F "subCopy=서브 문구 테스트" \
    -F "images=@315x258.png"

응답

{
  "bannerImageUrl": "https://t1.kakaocdn.net/b2/bannerImage/75799/MASKING/90676cbb7581e99eeb29ed6f879392d1.png",
  "imageType": "MASKING",
  "width": 1029,
  "height": 258
}

에러 코드

배너 홍보 이미지 생성 API 요청 시 발생할 수 있는 에러 코드 목록입니다.

에러 코드	설명
89950 `EXPRESS_API_ERROR`	배너생성툴 연동에 실패했습니다.
89951 `EXPRESS_TEMPLATE_TYPE_REQUIRED`	`TemplateType`(`OBJECT`, `THUMBNAIL`, `MASKING`, `TEXT`)은 필수입니다.
89952 `EXPRESS_MAIN_COPY_REQUIRED`	메인카피는 필수입니다.
89953 `EXPRESS_EXCEED_MAIN_COPY`	메인카피의 길이는 30자를 초과할 수 없습니다.
89954 `EXPRESS_EXCEED_SUB_COPY`	서브카피의 길이는 30자를 초과할 수 없습니다.
89955 `EXPRESS_NOTICE_TYPE_REQUIRED`	고지문구를 넣기 위해서는 고지 문구 유형(`LEGAL_NOTICE`, `LANDING_NOTICE`)이 필수입니다.
89956 `EXPRESS_APP_ICON_SUBCOPY_LEGAL_NOTICE_NOT_ALLOWED`	앱 아이콘 선택 시, 서브카피가 있는 상태에서 법적 고지문을 선택할 수 없습니다.
89957 `EXPRESS_APP_ICON_LANDING_NOTICE_NOT_ALLOWED`	앱 아이콘 선택 시, 채팅방 랜딩 고지문을 선택할 수 없습니다.
89958 `EXPRESS_INVALID_IMAGE`	이미지 파일에 문제가 있습니다.
89959 `EXPRESS_LOGO_NOT_SUPPORTED`	로고는 MASKING 배너에서만 지원합니다. (50KB 이하)
89960 `EXPRESS_ICON_NOT_SUPPORTED`	아이콘은 80KB 이하의 38x38 이미지만 지원합니다. (TEXT 배너 사용 불가)
89961 `EXPRESS_INVALID_TEXT_CHARACTERS`	한글, 영문, 숫자, 공백 및 허용된 특수문자만 입력 가능합니다.
89962 `EXPRESS_EXCEED_APP_ICON_TEXT`	아이콘 카피의 길이는 30자를 초과할 수 없습니다.
89963 `EXPRESS_EXCEED_BADGE_TEXT`	허용된 배지 문구의 길이를 초과했습니다.
89964 `EXPRESS_EXCEED_NOTICE`	허용된 고지 문구의 길이를 초과했습니다.
89970 `EXPRESS_BADGE_TYPE_REQUIRED`	배지를 넣기 위해서는 배지 타입이 필수입니다.
89971 `EXPRESS_INVALID_APP_ICON_IMAGE`	앱 아이콘 이미지가 잘못되었습니다.
89972 `EXPRESS_INVALID_BADGE_COLOR`	지원하지 않는 배지 색상입니다.
89973 `EXPRESS_USETALKICON_WITH_CUSTOMICON_NOT_ALLOWED`	톡 아이콘 사용 설정 시 별도 아이콘 이미지를 사용할 수 없습니다.
89974 `EXPRESS_BADGE_TEXT_REQUIRED`	배지 선택 시 배지 문구는 필수입니다.
89975 `EXPRESS_APP_ICON_TEXT_REQUIRED`	앱 아이콘 선택 시 앱 아이콘 문구는 필수입니다.
89976 `EXPRESS_NOTICE_TEXT_REQUIRED`	안내 문구 선택 시 고지 내용은 필수입니다.
89980 `EXPRESS_INVALID_OBJECT_BANNER_IMAGE`	OBJECT 배너는 150KB 이하의 315x258 png 이미지 1개만 지원합니다.
89981 `EXPRESS_OBJECT_BANNER_NOT_SUPPORTED`	OBJECT 배너에서 지원하지 않는 기능입니다.
89985 `EXPRESS_THUMBNAIL_TYPE_REQUIRED`	THUMBNAIL 배너는 ThumbnailType(SQUARE, BLUR, MULTI)이 필수입니다.
89986 `EXPRESS_INVALID_THUMBNAIL_BANNER_IMAGE`	THUMBNAIL 배너는 10MB 이하의 비투명 이미지 1개만 지원합니다. (MULTI 타입은 2개)
89987 `EXPRESS_THUMBNAIL_BANNER_NOT_SUPPORTED`	THUMBNAIL 배너에서 지원하지 않는 기능입니다.
89988 `EXPRESS_THUMBNAIL_TYPE_NOT_SUPPORTED`	선택하신 썸네일 유형에서 지원하지 않는 기능입니다.
89990 `EXPRESS_MASKING_TYPE_REQUIRED`	MASKING 배너는 `MaskingType`(`HALF_TOP`, `HALF_BOTTOM`)이 필수입니다.
89991 `EXPRESS_INVALID_MASKING_BANNER_IMAGE`	MASKING 배너는 비투명 이미지 1개만 지원합니다.
89992 `EXPRESS_MASKING_BANNER_NOT_SUPPORTED`	MASKING 배너에서 지원하지 않는 기능입니다.
89993 `EXPRESS_TEXT_BANNER_NOT_SUPPORTED`	TEXT 배너에서 지원하지 않는 기능입니다.
89994 `EXPRESS_NOT_SUPPORTED`	지원하지 않는 기능입니다.
89995 `EXPRESS_LOGO_REQUIRED`	MASKING 배너에서 로고는 필수입니다.
89996 `EXPRESS_INVALIDATION_WARNING`	입력하신 문구 중 가이드라인 영역을 미준수한 문구가 있습니다. 문구를 조정해 보세요.
90001 `ETC_BAD_REQUEST`	잘못된 요청입니다. (`TemplateType`, `ThumbnailType`, `MaskingType`, `BadgeType`, `NoticeType` 에 규정되지 않은 값을 입력한 경우)

인하우스/공동체 문서

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기